@brainwav/diagram 1.0.7 → 1.1.0

package/src/schema/erd-model.js

@@ -0,0 +1,176 @@
+function sanitizeToken(value) {
+  return String(value || '')
+    .trim()
+    .replace(/[`"'\\]/g, '')
+    .replace(/[^A-Za-z0-9_]/g, '_');
+}
+
+function canonicalEntityName(value) {
+  const token = sanitizeToken(value);
+  return token ? token.toUpperCase() : '';
+}
+
+function canonicalAttributeName(value) {
+  return sanitizeToken(value);
+}
+
+function canonicalType(value) {
+  const token = sanitizeToken(value);
+  return token || 'unknown';
+}
+
+function toKeyFlags(flags) {
+  const order = ['PK', 'FK', 'UK'];
+  const seen = new Set((Array.isArray(flags) ? flags : []).map((flag) => String(flag).toUpperCase()));
+  return order.filter((flag) => seen.has(flag));
+}
+
+function mergeAttributes(existingAttributes, incomingAttributes) {
+  const byName = new Map();
+
+  for (const attribute of [...existingAttributes, ...incomingAttributes]) {
+    const name = canonicalAttributeName(attribute?.name);
+    if (!name) continue;
+    const prev = byName.get(name);
+    const next = {
+      name,
+      type: canonicalType(attribute?.type),
+      nullable: Boolean(attribute?.nullable),
+      keyFlags: toKeyFlags(attribute?.keyFlags),
+    };
+
+    if (!prev) {
+      byName.set(name, next);
+      continue;
+    }
+
+    const mergedFlags = toKeyFlags([...(prev.keyFlags || []), ...(next.keyFlags || [])]);
+    byName.set(name, {
+      name,
+      type: prev.type !== 'unknown' ? prev.type : next.type,
+      nullable: prev.nullable || next.nullable,
+      keyFlags: mergedFlags,
+    });
+  }
+
+  const keyPriority = ['PK', 'FK', 'UK'];
+  const score = (attribute) => {
+    if ((attribute.keyFlags || []).length === 0) return keyPriority.length;
+    const positions = attribute.keyFlags
+      .map((flag) => keyPriority.indexOf(flag))
+      .filter((index) => index >= 0);
+    return positions.length > 0 ? Math.min(...positions) : keyPriority.length;
+  };
+
+  return [...byName.values()].sort((a, b) => {
+    const scoreDiff = score(a) - score(b);
+    if (scoreDiff !== 0) return scoreDiff;
+    return a.name.localeCompare(b.name);
+  });
+}
+
+function normalizeErdModel(input) {
+  const entitiesInput = Array.isArray(input?.entities) ? input.entities : [];
+  const relationshipsInput = Array.isArray(input?.relationships) ? input.relationships : [];
+  const diagnostics = Array.isArray(input?.diagnostics) ? input.diagnostics : [];
+  const sourceFiles = Array.isArray(input?.sourceFiles) ? input.sourceFiles : [];
+  const sourcePrecedence = Array.isArray(input?.sourcePrecedence) ? input.sourcePrecedence : [];
+
+  const entitiesByName = new Map();
+  for (const entity of entitiesInput) {
+    const name = canonicalEntityName(entity?.name);
+    if (!name) continue;
+    const source = entity?.source === 'inferred' ? 'inferred' : 'explicit';
+    const existing = entitiesByName.get(name);
+    const attributes = mergeAttributes(existing?.attributes || [], entity?.attributes || []);
+    const merged = {
+      name,
+      source: existing?.source === 'explicit' || source === 'explicit' ? 'explicit' : 'inferred',
+      attributes,
+    };
+    entitiesByName.set(name, merged);
+  }
+
+  const entities = [...entitiesByName.values()].sort((a, b) => a.name.localeCompare(b.name));
+  const entitySet = new Set(entities.map((entity) => entity.name));
+  const relationshipMap = new Map();
+
+  for (const relationship of relationshipsInput) {
+    const fromEntity = canonicalEntityName(relationship?.fromEntity);
+    const toEntity = canonicalEntityName(relationship?.toEntity);
+    if (!fromEntity || !toEntity) continue;
+    if (!entitySet.has(fromEntity) || !entitySet.has(toEntity)) continue;
+
+    const provenance = relationship?.provenance === 'inferred' ? 'inferred' : 'explicit';
+    const cardinality = String(relationship?.cardinality || '||--o{');
+    const relationshipKey = `${fromEntity}|${toEntity}|${cardinality}`;
+    const existing = relationshipMap.get(relationshipKey);
+    if (!existing || existing.provenance === 'inferred') {
+      relationshipMap.set(relationshipKey, {
+        fromEntity,
+        toEntity,
+        cardinality,
+        provenance,
+      });
+    }
+  }
+
+  const relationships = [...relationshipMap.values()].sort((a, b) => {
+    if (a.fromEntity !== b.fromEntity) return a.fromEntity.localeCompare(b.fromEntity);
+    if (a.toEntity !== b.toEntity) return a.toEntity.localeCompare(b.toEntity);
+    if (a.provenance !== b.provenance) return a.provenance.localeCompare(b.provenance);
+    return a.cardinality.localeCompare(b.cardinality);
+  });
+
+  return {
+    entities,
+    relationships,
+    diagnostics,
+    sourceFiles: [...new Set(sourceFiles)].sort(),
+    sourcePrecedence: [...new Set(sourcePrecedence)],
+  };
+}
+
+function renderErdMermaid(model, options = {}) {
+  const entities = Array.isArray(model?.entities) ? model.entities : [];
+  const relationships = Array.isArray(model?.relationships) ? model.relationships : [];
+  const lines = ['erDiagram'];
+
+  if (options.lowConfidenceMarker) {
+    const percent = typeof options.inferenceShare === 'number'
+      ? Math.round(options.inferenceShare * 100)
+      : null;
+    const marker = percent === null
+      ? 'low-confidence: inferred relationships are above preferred threshold'
+      : `low-confidence: inferred relationships are ${percent}% of all relationships`;
+    lines.push(`  %% ${marker}`);
+  }
+
+  for (const entity of entities) {
+    lines.push(`  ${entity.name} {`);
+    for (const attribute of entity.attributes || []) {
+      const flags = (attribute.keyFlags || []).join(' ');
+      const suffix = flags ? ` ${flags}` : '';
+      lines.push(`    ${canonicalType(attribute.type)} ${canonicalAttributeName(attribute.name)}${suffix}`);
+    }
+    lines.push('  }');
+  }
+
+  if (relationships.length > 0) {
+    lines.push('');
+  }
+
+  for (const relationship of relationships) {
+    lines.push(
+      `  ${relationship.fromEntity} ${relationship.cardinality} ${relationship.toEntity} : ${relationship.provenance}`
+    );
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  canonicalEntityName,
+  normalizeErdModel,
+  renderErdMermaid,
+};

package/src/schema/rules-schema.js

@@ -0,0 +1,170 @@
+const { z } = require('zod');
+
+/**
+ * Zod schema for architecture rules validation
+ * Used to validate .architecture.yml files
+ */
+
+// Single rule schema
+const ruleSchema = z.object({
+  name: z.string()
+    .min(1, 'Rule name is required')
+    .max(100, 'Rule name must be less than 100 characters'),
+
+  description: z.string()
+    .max(500, 'Description must be less than 500 characters')
+    .optional(),
+
+  baseline: z.number()
+    .int('Baseline must be an integer')
+    .min(0, 'Baseline must be non-negative')
+    .optional()
+    .describe('Accepted violation count. New violations beyond this will fail.'),
+
+  layer: z.union([
+    z.string().min(1, 'Layer pattern is required'),
+    z.array(z.string().min(1, 'Layer pattern cannot be empty'))
+      .min(1, 'At least one layer pattern is required')
+  ]),
+  
+  // Import constraint rules
+  must_not_import_from: z.array(z.string())
+    .optional()
+    .describe('List of patterns that files in this layer must not import'),
+  
+  may_import_from: z.array(z.string())
+    .optional()
+    .describe('Whitelist of allowed import patterns'),
+  
+  must_import_from: z.array(z.string())
+    .optional()
+    .describe('List of patterns that files in this layer must import'),
+
+  // Inward-only constraint: files in this layer cannot be imported by other inward_only layers
+  inward_only: z.boolean()
+    .optional()
+    .describe('If true, other inward_only layers cannot import from this layer'),
+
+}).refine(
+  (data) => {
+    // At least one constraint must be specified
+    // Must check for non-empty arrays (empty array is truthy but invalid)
+    const hasMustNotImport = Array.isArray(data.must_not_import_from) && data.must_not_import_from.length > 0;
+    const hasMayImport = Array.isArray(data.may_import_from) && data.may_import_from.length > 0;
+    const hasMustImport = Array.isArray(data.must_import_from) && data.must_import_from.length > 0;
+    const hasInwardOnly = data.inward_only === true;
+    return hasMustNotImport || hasMayImport || hasMustImport || hasInwardOnly;
+  },
+  {
+    message: 'Rule must specify at least one constraint (must_not_import_from, may_import_from, must_import_from, or inward_only)',
+    path: ['constraints']
+  }
+).refine(
+  (data) => {
+    // Validate that layer patterns don't contain '..' or absolute paths
+    const patterns = Array.isArray(data.layer) ? data.layer : [data.layer];
+    return patterns.every(p => !p.includes('..') && !p.startsWith('/'));
+  },
+  {
+    message: 'Layer patterns cannot contain ".." or absolute paths',
+    path: ['layer']
+  }
+);
+
+// Full configuration schema
+const configSchema = z.object({
+  version: z.string()
+    .regex(/^[0-9]+\.[0-9]+$/, 'Version must be in format "X.Y"')
+    .default('1.0'),
+  
+  extends: z.string()
+    .optional()
+    .describe('Path to base configuration file to extend'),
+  
+  rules: z.array(ruleSchema)
+    .min(1, 'At least one rule is required'),
+}).strict(); // Reject unknown properties for safety
+
+/**
+ * Validate configuration against schema
+ * @param {Object} config - Parsed configuration
+ * @returns {Object} Validation result
+ */
+function validateConfig(config) {
+  const result = configSchema.safeParse(config);
+  
+  if (!result.success) {
+    const errors = result.error.issues.map(err => ({
+      path: err.path.join('.'),
+      message: err.message,
+      value: String(err.received).slice(0, 100) // Truncate large values
+    }));
+    
+    return {
+      valid: false,
+      errors
+    };
+  }
+  
+  return {
+    valid: true,
+    data: result.data
+  };
+}
+
+/**
+ * Validate a single rule
+ * @param {Object} rule - Rule configuration
+ * @returns {Object} Validation result
+ */
+function validateRule(rule) {
+  const result = ruleSchema.safeParse(rule);
+  
+  if (!result.success) {
+    return {
+      valid: false,
+      errors: result.error.issues.map(err => ({
+        path: err.path.join('.'),
+        message: err.message
+      }))
+    };
+  }
+  
+  return {
+    valid: true,
+    data: result.data
+  };
+}
+
+/**
+ * Get default configuration
+ * @returns {Object}
+ */
+function getDefaultConfig() {
+  return {
+    version: '1.0',
+    rules: [
+      {
+        name: 'Domain isolation',
+        description: 'Domain logic should not depend on UI',
+        layer: 'src/domain',
+        must_not_import_from: ['src/ui', 'src/components']
+      },
+      {
+        name: 'API contract',
+        description: 'API routes only use domain and shared',
+        layer: 'src/api',
+        may_import_from: ['src/domain', 'src/shared', 'src/types'],
+        must_not_import_from: ['src/ui']
+      }
+    ]
+  };
+}
+
+module.exports = {
+  configSchema,
+  ruleSchema,
+  validateConfig,
+  validateRule,
+  getDefaultConfig
+};

package/src/utils/suggestions.js

@@ -0,0 +1,67 @@
+const chalk = require('chalk');
+
+/**
+ * Compute the Levenshtein edit distance between two strings.
+ *
+ * @param {string} a - First string to compare.
+ * @param {string} b - Second string to compare.
+ * @returns {number} The minimum number of single-character insertions, deletions or substitutions required to transform `a` into `b`.
+ */
+function levenshtein(a, b) {
+  const rows = a.length + 1;
+  const cols = b.length + 1;
+  const matrix = Array.from({ length: rows }, () => Array(cols).fill(0));
+
+  for (let i = 0; i < rows; i += 1) matrix[i][0] = i;
+  for (let j = 0; j < cols; j += 1) matrix[0][j] = j;
+
+  for (let i = 1; i < rows; i += 1) {
+    for (let j = 1; j < cols; j += 1) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,
+        matrix[i][j - 1] + 1,
+        matrix[i - 1][j - 1] + cost
+      );
+    }
+  }
+
+  return matrix[a.length][b.length];
+}
+
+/**
+ * Selects the closest matching option to the given input from an array of candidates.
+ *
+ * Compares `input` (stringified and lowercased) against each element of `options` (stringified and lowercased)
+ * using Levenshtein edit distance and returns the candidate with the lowest distance only if that distance
+ * is within an acceptance threshold proportional to the input length; otherwise returns `null`.
+ *
+ * @param {*} input - Value to match; it will be converted to a string for comparison.
+ * @param {Array<*>} options - Array of candidate values (each will be converted to a string).
+ * @returns {*} The best matching option from `options` if its edit distance is acceptable, `null` otherwise.
+ */
+function findClosestMatch(input, options) {
+  if (!input || !Array.isArray(options) || options.length === 0) return null;
+
+  const normalizedInput = String(input).toLowerCase();
+  const scored = options
+    .map((option) => ({ option, score: levenshtein(normalizedInput, String(option).toLowerCase()) }))
+    .sort((a, b) => a.score - b.score);
+
+  const best = scored[0];
+  return best.score <= Math.max(2, Math.floor(normalizedInput.length / 3)) ? best.option : null;
+}
+
+/**
+ * Format a suggestion message for display.
+ * @param {string} suggestion - The suggested alternative to present to the user.
+ * @returns {string} A grey-coloured string in the form "   Did you mean: <suggestion>".
+ */
+function formatSuggestion(suggestion) {
+  return chalk.gray(`   Did you mean: ${suggestion}`);
+}
+
+module.exports = {
+  findClosestMatch,
+  formatSuggestion,
+};

package/src/video.js

@@ -2,7 +2,6 @@ const { chromium } = require('playwright');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
-const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 const { pathToFileURL } = require('url');
 const chalk = require('chalk');
@@ -309,8 +308,8 @@ ${escapedCode}
     browser = await chromium.launch({ timeout: 60000 });
     const page = await browser.newPage();
     
-    const randomId = crypto.randomBytes(16).toString('hex');
-    tempFile = path.join(os.tmpdir(), `diagram-${Date.now()}-${randomId}.html`);
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'diagram-svg-'), { mode: 0o700 });
+    tempFile = path.join(tempDir, 'diagram.html');
     fs.writeFileSync(tempFile, htmlContent);
     
     const fileUrl = pathToFileURL(tempFile).href;
@@ -362,7 +361,7 @@ ${escapedCode}
     browser = null;
     
     if (tempFile && fs.existsSync(tempFile)) {
-      fs.unlinkSync(tempFile);
+      try { fs.rmSync(path.dirname(tempFile), { recursive: true, force: true }); } catch (e) {}
     }
     
     if (svgContent) {
@@ -379,7 +378,7 @@ ${escapedCode}
       try { await browser.close(); } catch (e) {}
     }
     if (tempFile && fs.existsSync(tempFile)) {
-      try { fs.unlinkSync(tempFile); } catch (e) {}
+      try { fs.rmSync(path.dirname(tempFile), { recursive: true, force: true }); } catch (e) {}
     }
     throw error;
   }