@brainwav/diagram 1.0.8 → 1.1.0

package/src/rules/types/import-rule.js

@@ -0,0 +1,286 @@
+const { Rule } = require('./base');
+const path = require('path');
+const picomatch = require('picomatch');
+
+/**
+ * Import constraint rule
+ * Validates imports against allowed/forbidden patterns
+ * Supports inward_only for directional layer constraints
+ */
+class ImportRule extends Rule {
+  /**
+   * Get compiled layer matchers for this rule
+   * @returns {Array<Function>}
+   */
+  get layerMatchers() {
+    if (!this._layerMatchers) {
+      const layers = Array.isArray(this.layer) ? this.layer : [this.layer];
+      this._layerMatchers = layers
+        .filter(l => typeof l === 'string' && l.trim() !== '')
+        .map(l => picomatch(l.trim(), { dot: true }));
+    }
+    return this._layerMatchers;
+  }
+
+  /**
+   * Validate a file against this rule
+   * @param {Object} file - Component file object
+   * @param {ComponentGraph} graph - Component graph for lookups
+   * @param {Object} context - Optional context with inwardOnlyMatchers
+   * @returns {Array<Violation>} Array of violations
+   */
+  validate(file, graph, context = {}) {
+    const violations = [];
+    const imports = Array.isArray(file?.imports) ? file.imports : [];
+
+    const truncateText = (value, max = 100) => String(value ?? '').slice(0, max);
+
+    // Helper to safely extract import path
+    const getImportPath = (importInfo) => {
+      if (typeof importInfo === 'string') return importInfo;
+      if (importInfo && typeof importInfo.path === 'string') return importInfo.path;
+      return null;
+    };
+
+    // Helper to safely extract line number
+    const getLineNumber = (importInfo) => {
+      if (importInfo && Number.isInteger(importInfo.line) && importInfo.line > 0) {
+        return importInfo.line;
+      }
+      return undefined;
+    };
+
+    // Check must_not_import_from constraints
+    if (Array.isArray(this.config.must_not_import_from)) {
+      for (const importInfo of imports) {
+        const importPath = getImportPath(importInfo);
+        if (!importPath) continue;
+        
+        for (const forbidden of this.config.must_not_import_from) {
+          try {
+            if (this._matchesPattern(importPath, forbidden, file.filePath)) {
+              violations.push({
+                ruleName: this.name,
+                severity: 'error',
+                file: file.filePath,
+                line: getLineNumber(importInfo),
+                message: `Forbidden import: "${truncateText(importPath)}" matches "${truncateText(forbidden)}"`,
+                suggestion: 'Remove this import or add to allowed list',
+                relatedFile: importPath
+              });
+              break; // Found match, no need to check other forbidden patterns
+            }
+          } catch (e) {
+            // Regex error, skip this pattern
+          }
+        }
+      }
+    }
+
+    // Check may_import_from whitelist constraints
+    if (Array.isArray(this.config.may_import_from) && this.config.may_import_from.length > 0) {
+      for (const importInfo of imports) {
+        const importPath = getImportPath(importInfo);
+        if (!importPath) continue;
+        
+        let isAllowed = false;
+        for (const allowed of this.config.may_import_from) {
+          try {
+            if (this._matchesPattern(importPath, allowed, file.filePath)) {
+              isAllowed = true;
+              break; // Found match, no need to check other allowed patterns
+            }
+          } catch (e) {
+            // Regex error, continue checking
+          }
+        }
+        
+        if (!isAllowed) {
+          violations.push({
+            ruleName: this.name,
+            severity: 'error',
+            file: file.filePath,
+            line: getLineNumber(importInfo),
+            message: `Import not in whitelist: "${truncateText(importPath)}"`,
+            suggestion: `Add to may_import_from or use allowed import`,
+            relatedFile: importPath
+          });
+        }
+      }
+    }
+
+    // Check must_import_from required constraints
+    if (Array.isArray(this.config.must_import_from) && this.config.must_import_from.length > 0) {
+      for (const required of this.config.must_import_from) {
+        let hasImport = false;
+        for (const importInfo of imports) {
+          const importPath = getImportPath(importInfo);
+          if (!importPath) continue;
+          
+          try {
+            if (this._matchesPattern(importPath, required, file.filePath)) {
+              hasImport = true;
+              break;
+            }
+          } catch (e) {
+            // Regex error, continue checking
+          }
+        }
+        
+        if (!hasImport) {
+          violations.push({
+            ruleName: this.name,
+            severity: 'error',
+            file: file.filePath,
+            message: `Missing required import matching "${truncateText(required)}"`,
+            suggestion: `Add an import that matches "${truncateText(required, 200)}"`
+          });
+        }
+      }
+    }
+
+    // Check inward_only constraint (who imports THIS file)
+    // This checks DEPENDENTS, not dependencies
+    if (this.config.inward_only === true) {
+      const protectedMatchers = context?.inwardOnlyMatchers;
+      if (protectedMatchers && protectedMatchers.size > 0 && file?.name) {
+        // Get who imports THIS file (dependents)
+        const dependents = graph.getDependents(file.name);
+
+        for (const dependent of dependents) {
+          if (!dependent?.filePath) continue;
+
+          // Fast path: skip if dependent is in same layer
+          if (this.layerMatchers.length > 0 && this.matchesLayer(dependent.filePath, this.layerMatchers)) {
+            continue;
+          }
+
+          // Check if dependent is in ANOTHER protected layer
+          for (const [ruleName, { matchers }] of protectedMatchers) {
+            if (ruleName === this.name) continue; // Skip self
+
+            if (matchers && matchers.length > 0 && this.matchesLayer(dependent.filePath, matchers)) {
+              violations.push({
+                ruleName: this.name,
+                severity: 'error',
+                file: dependent.filePath,        // The VIOLATOR (dependent file)
+                line: this._findImportLine(dependent, file.filePath),
+                message: `Cannot import from protected layer "${this.name}": layer "${ruleName}" has inward_only constraint`,
+                suggestion: `Move shared logic to an unprotected module (e.g., src/shared/) or remove inward_only from one layer`,
+                relatedFile: file.filePath        // The PROTECTED file
+              });
+              break; // One violation per dependent, not per matching rule
+            }
+          }
+        }
+      }
+    }
+
+    return violations;
+  }
+
+  /**
+   * Find the line number of the import that targets a specific file
+   * @param {Object} dependent - Dependent component with imports
+   * @param {string} targetFilePath - The file being imported
+   * @returns {number|undefined}
+   */
+  _findImportLine(dependent, targetFilePath) {
+    const imports = dependent?.imports || [];
+    for (const imp of imports) {
+      const importPath = typeof imp === 'string' ? imp : imp?.path;
+      if (!importPath) continue;
+
+      // Check if this import resolves to targetFilePath
+      if (this._resolvesTo(importPath, dependent.filePath, targetFilePath)) {
+        return typeof imp === 'object' ? imp.line : undefined;
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Check if an import path resolves to a target file path
+   * @param {string} importPath - The import path (may be relative)
+   * @param {string} fromFile - The file containing the import
+   * @param {string} targetFilePath - The expected resolved path
+   * @returns {boolean}
+   */
+  _resolvesTo(importPath, fromFile, targetFilePath) {
+    // External packages never match internal paths
+    if (!importPath?.startsWith('.')) {
+      return false;
+    }
+
+    const fromDir = path.dirname(fromFile || '.');
+    const resolved = path.normalize(path.join(fromDir, importPath));
+
+    // Check with common extensions
+    const extensions = ['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs'];
+    for (const ext of extensions) {
+      if (resolved + ext === targetFilePath) return true;
+    }
+
+    // Check index files
+    for (const ext of extensions) {
+      if (path.join(resolved, 'index' + ext) === targetFilePath) return true;
+    }
+
+    return resolved === targetFilePath;
+  }
+
+  /**
+   * Check if an import path matches a pattern
+   * @param {string} importPath - The import path
+   * @param {string} pattern - The pattern to match against
+   * @param {string} sourceFile - The file containing the import (for relative path resolution)
+ * @returns {boolean}
+   */
+  _matchesPattern(importPath, pattern, sourceFile) {
+    // Handle empty or invalid inputs
+    if (!pattern || typeof pattern !== 'string' || pattern.trim() === '') {
+      return false;
+    }
+    if (!importPath || typeof importPath !== 'string') {
+      return false;
+    }
+    
+    // Normalize paths for comparison
+    const normalizedImport = importPath.replace(/\\/g, '/');
+    const normalizedPattern = pattern.replace(/\\/g, '/').replace(/\/$/, ''); // Remove trailing slash
+    
+    // Exact match
+    if (normalizedImport === normalizedPattern) {
+      return true;
+    }
+    
+    // Check if import is within the pattern directory (path boundary)
+    // e.g., 'src/ui/Button' matches 'src/ui' but 'src/ui-core' does not
+    if (normalizedImport.startsWith(normalizedPattern + '/')) {
+      return true;
+    }
+    
+    // Glob pattern matching for patterns with wildcards
+    if (normalizedPattern.includes('*') || normalizedPattern.includes('?')) {
+      try {
+        const matcher = picomatch(normalizedPattern, { dot: true });
+        return matcher(normalizedImport);
+      } catch (e) {
+        // Invalid glob pattern
+        return false;
+      }
+    }
+    
+    // Handle relative imports by resolving against source file
+    if (importPath.startsWith('.')) {
+      const sourceDir = path.dirname(sourceFile || '.').replace(/\\/g, '/');
+      const resolvedPath = path.posix.normalize(path.posix.join(sourceDir, normalizedImport));
+      return resolvedPath === normalizedPattern || 
+             resolvedPath.startsWith(normalizedPattern + '/');
+    }
+    
+    return false;
+  }
+}
+
+module.exports = { ImportRule };

package/src/rules.js

@@ -0,0 +1,380 @@
+const YAML = require('yaml');
+const fs = require('fs');
+const path = require('path');
+const picomatch = require('picomatch');
+
+const MAX_CONFIG_SIZE = 1024 * 1024; // 1MB limit
+const MAX_PATTERN_CACHE_SIZE = 5000;
+
+/**
+ * Architecture Rules Engine
+ * Validates codebase against declarative rules
+ */
+class RulesEngine {
+  constructor() {
+    this.patternCache = new Map();
+  }
+
+  /**
+   * Load and parse YAML configuration file
+   * @param {string} configPath - Path to .architecture.yml
+   * @returns {Object} Parsed configuration
+   */
+  loadConfig(configPath) {
+    // Security: Read file first, then check size to avoid TOCTOU race
+    let content;
+    try {
+      content = fs.readFileSync(configPath, 'utf8');
+    } catch (e) {
+      throw new Error(`Config file not found or not accessible: ${configPath}`);
+    }
+    
+    const contentSize = Buffer.byteLength(content, 'utf8');
+    if (contentSize > MAX_CONFIG_SIZE) {
+      throw new Error(
+        `Config file too large (${contentSize} bytes)`
+      );
+    }
+
+    try {
+      return YAML.parse(content, {
+        prettyErrors: true,
+        strict: true,
+        maxAliasCount: 100, // Prevent Billion Laughs attack
+        customTags: [] // Disable dangerous tags like !!js/function
+      });
+    } catch (error) {
+      const enhanced = new Error(
+        `Failed to parse ${configPath}: ${error.message}`
+      );
+      enhanced.filepath = configPath;
+      enhanced.originalError = error;
+      throw enhanced;
+    }
+  }
+
+  /**
+   * Validate a pattern for security issues
+   * @param {string} pattern - Glob pattern
+   * @param {string} context - Context for error messages
+   */
+  validatePattern(pattern, context = 'pattern') {
+    if (typeof pattern !== 'string' || pattern.trim() === '') {
+      throw new Error(`Invalid ${context}: pattern must be a non-empty string`);
+    }
+    if (pattern.includes('\0')) {
+      const preview = pattern.slice(0, 50) + (pattern.length > 50 ? '...' : '');
+      throw new Error(`Invalid ${context}: null bytes are not allowed in pattern: "${preview}"`);
+    }
+
+    const normalizedPattern = path.posix.normalize(pattern.trim().replace(/\\/g, '/'));
+    
+    if (normalizedPattern === '..' || normalizedPattern.startsWith('../')) {
+      throw new Error(
+        `Invalid ${context}: directory traversal not allowed`
+      );
+    }
+    if (path.posix.isAbsolute(normalizedPattern) || /^[a-zA-Z]:\//.test(normalizedPattern)) {
+      throw new Error(
+        `Invalid ${context}: absolute paths not allowed`
+      );
+    }
+  }
+
+  /**
+   * Get or create a compiled pattern matcher
+   * @param {string} pattern - Glob pattern
+   * @param {Object} options - picomatch options
+   * @returns {Function}
+   */
+  getMatcher(pattern, options = { dot: true }) {
+    // Validate options are serializable
+    let optionsKey;
+    try {
+      optionsKey = JSON.stringify(options);
+    } catch (e) {
+      optionsKey = String(options);
+    }
+    
+    // Include options in cache key
+    const key = `${pattern}::${optionsKey}`;
+    
+    if (!this.patternCache.has(key)) {
+      this.validatePattern(pattern);
+      if (this.patternCache.size >= MAX_PATTERN_CACHE_SIZE) {
+        this.patternCache.clear();
+      }
+      this.patternCache.set(key, picomatch(pattern, options));
+    }
+    
+    return this.patternCache.get(key);
+  }
+
+  /**
+   * Compile layer patterns for a rule
+   * @param {Object} rule - Rule configuration
+   * @returns {Array<Function>} Compiled matchers
+   */
+  compileLayerPatterns(rule) {
+    const layers = Array.isArray(rule?.layer) ? rule.layer : [rule?.layer];
+    const normalizedLayers = layers
+      .filter(layer => typeof layer === 'string' && layer.trim() !== '')
+      .map(layer => layer.trim());
+
+    if (normalizedLayers.length === 0) {
+      throw new Error(`Rule "${rule?.name || 'unnamed'}" has no valid layer patterns`);
+    }
+
+    return normalizedLayers.map(layer => this.getMatcher(layer, { dot: true }));
+  }
+
+  /**
+   * Validate rules against component graph
+   * @param {Array<Rule>} rules - Rule instances
+   * @param {ComponentGraph} graph - Component graph
+   * @returns {Object} Validation results
+   */
+  validate(rules, graph) {
+    if (!graph || typeof graph.getFilesInLayer !== 'function') {
+      throw new TypeError('graph must expose getFilesInLayer(matchers)');
+    }
+
+    const safeRules = Array.isArray(rules) ? rules : [];
+    const results = {
+      summary: {
+        total: safeRules.length,
+        passed: 0,
+        failed: 0,
+        violations: 0
+      },
+      rules: []
+    };
+
+    const seenRuleNames = new Set();
+
+    // Pre-compute inward_only layer matchers ONCE (performance optimization)
+    const MAX_INWARD_ONLY_RULES = 50;
+    const inwardOnlyMatchers = new Map();
+
+    for (const rule of safeRules) {
+      if (rule?.config?.inward_only === true && rule?.config?.layer) {
+        const ruleName = rule.name || 'unnamed';
+        const matchers = this.compileLayerPatterns({ layer: rule.config.layer });
+        inwardOnlyMatchers.set(ruleName, {
+          pattern: rule.config.layer,
+          matchers
+        });
+      }
+    }
+
+    // Security limit: prevent config explosion
+    if (inwardOnlyMatchers.size > MAX_INWARD_ONLY_RULES) {
+      throw new Error(
+        `Too many inward_only rules (${inwardOnlyMatchers.size}). Maximum is ${MAX_INWARD_ONLY_RULES}.`
+      );
+    }
+
+    // Build context for explicit parameter passing (no graph mutation)
+    const context = { inwardOnlyMatchers };
+
+    for (let index = 0; index < safeRules.length; index++) {
+      const rule = safeRules[index] || {};
+      const ruleName =
+        typeof rule.name === 'string' && rule.name.trim() !== ''
+          ? rule.name
+          : `rule-${index + 1}`;
+      const ruleResult = {
+        name: ruleName,
+        description: typeof rule.description === 'string' ? rule.description : '',
+        status: 'passed',
+        filesChecked: 0,
+        violations: []
+      };
+
+      if (seenRuleNames.has(ruleName)) {
+        ruleResult.violations.push({
+          ruleName,
+          severity: 'error',
+          message: `Duplicate rule name "${ruleName}" detected`
+        });
+      } else {
+        seenRuleNames.add(ruleName);
+      }
+
+      let filesInLayer = [];
+      try {
+        const matchers = this.compileLayerPatterns(rule);
+        filesInLayer = graph.getFilesInLayer(matchers);
+        ruleResult.filesChecked = filesInLayer.length;
+      } catch (error) {
+        ruleResult.status = 'failed';
+        ruleResult.violations.push({
+          ruleName,
+          severity: 'error',
+          message: `Rule setup failed: ${error.message}`
+        });
+        results.summary.failed++;
+        results.summary.violations += ruleResult.violations.length;
+        results.rules.push(ruleResult);
+        continue;
+      }
+
+      // Skip if no files match
+      if (filesInLayer.length === 0) {
+        if (ruleResult.violations.length > 0) {
+          ruleResult.status = 'failed';
+          results.summary.failed++;
+          results.summary.violations += ruleResult.violations.length;
+        } else {
+          ruleResult.status = 'skipped';
+          ruleResult.message = 'No files matched layer pattern';
+        }
+        results.rules.push(ruleResult);
+        continue;
+      }
+
+      if (typeof rule.validate !== 'function') {
+        ruleResult.violations.push({
+          ruleName,
+          severity: 'error',
+          message: `Rule "${ruleName}" does not implement validate()`
+        });
+      }
+
+      // Validate each file with error handling per rule
+      for (const file of filesInLayer) {
+        if (!file || typeof file !== 'object') continue;
+        try {
+          if (typeof rule.validate !== 'function') {
+            break;
+          }
+          const violations = rule.validate(file, graph, context);
+          if (Array.isArray(violations) && violations.length > 0) {
+            ruleResult.violations.push(...violations);
+          } else if (violations != null && !Array.isArray(violations)) {
+            ruleResult.violations.push({
+              ruleName,
+              severity: 'error',
+              file: file.filePath,
+              message: 'Rule returned invalid violation payload'
+            });
+          }
+        } catch (validationError) {
+          ruleResult.violations.push({
+            ruleName,
+            severity: 'error',
+            file: file.filePath,
+            message: `Rule validation failed: ${validationError.message}`
+          });
+        }
+      }
+
+      // Determine status
+      if (ruleResult.violations.length > 0) {
+        ruleResult.status = 'failed';
+        results.summary.failed++;
+        results.summary.violations += ruleResult.violations.length;
+      } else {
+        results.summary.passed++;
+      }
+
+      results.rules.push(ruleResult);
+    }
+
+    return results;
+  }
+
+  /**
+   * Find configuration file
+   * @param {string} searchPath - Directory to search
+   * @returns {string|null} Path to config file or null
+   */
+  findConfig(searchPath) {
+    const configNames = [
+      '.architecture.yml',
+      '.architecture.yaml',
+      'architecture.config.yml',
+      'architecture.config.yaml'
+    ];
+
+    // Case-insensitive search on Windows
+    const isWindows = process.platform === 'win32';
+    
+    for (const name of configNames) {
+      const fullPath = path.join(searchPath, name);
+      if (fs.existsSync(fullPath)) {
+        return fullPath;
+      }
+      
+      // On Windows, also try case-insensitive match
+      if (isWindows) {
+        const lowerName = name.toLowerCase();
+        try {
+          const files = fs.readdirSync(searchPath);
+          const match = files.find(f => f.toLowerCase() === lowerName);
+          if (match) {
+            return path.join(searchPath, match);
+          }
+        } catch (e) {
+          // Directory not readable
+        }
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Preview which files match each rule (dry-run mode)
+   * @param {Array<Rule>} rules - Rule instances
+   * @param {ComponentGraph} graph - Component graph
+   * @returns {Object} File matching results
+   */
+  previewMatches(rules, graph) {
+    const preview = {
+      rules: []
+    };
+
+    if (!graph || typeof graph.getFilesInLayer !== 'function') {
+      return {
+        rules: [{
+          name: 'preview',
+          layer: '',
+          error: 'Invalid graph input'
+        }]
+      };
+    }
+    
+    const MAX_PREVIEW_FILES = 100; // Limit output size
+    const safeRules = Array.isArray(rules) ? rules : [];
+
+    for (let index = 0; index < safeRules.length; index++) {
+      const rule = safeRules[index] || {};
+      try {
+        const matchers = this.compileLayerPatterns(rule);
+        const filesInLayer = graph.getFilesInLayer(matchers);
+        
+        const matchedFiles = filesInLayer.map(f => f.filePath);
+        const truncated = matchedFiles.length > MAX_PREVIEW_FILES;
+        
+        preview.rules.push({
+          name: rule.name,
+          layer: rule.layer,
+          matchedFiles: truncated ? matchedFiles.slice(0, MAX_PREVIEW_FILES) : matchedFiles,
+          truncated: truncated,
+          totalFiles: matchedFiles.length
+        });
+      } catch (e) {
+        preview.rules.push({
+          name: rule.name || `rule-${index + 1}`,
+          layer: rule.layer,
+          error: e.message
+        });
+      }
+    }
+
+    return preview;
+  }
+}
+
+module.exports = { RulesEngine, MAX_CONFIG_SIZE };