@equilateral_ai/mindmeld 3.2.0 → 3.3.1

package/src/core/parsers/adrParser.js

@@ -0,0 +1,479 @@
+/**
+ * ADR Parser - Parse Architecture Decision Records into YAML standards format
+ *
+ * Parses ADR markdown files with standard sections:
+ *   Title, Status, Context, Decision, Consequences
+ *
+ * Extracts:
+ *   - Rules from Decision section with action types (ALWAYS/NEVER/USE/PREFER/AVOID)
+ *   - Anti-patterns from Consequences negative items
+ *   - Context for applicability
+ *
+ * Returns YAML-compatible object matching equilateral-standards schema:
+ *   { id, category, priority, rules, anti_patterns, context }
+ *
+ * @module parsers/adrParser
+ */
+
+/**
+ * Action keywords that indicate rule types in decision text
+ */
+const ACTION_PATTERNS = [
+  { regex: /\b(?:must|shall|always|required)\b/i, action: 'ALWAYS' },
+  { regex: /\b(?:must not|shall not|never|prohibited|forbidden)\b/i, action: 'NEVER' },
+  { regex: /\b(?:will use|adopt|choose|selected|use)\b/i, action: 'USE' },
+  { regex: /\b(?:prefer|should|recommended|favor)\b/i, action: 'PREFER' },
+  { regex: /\b(?:avoid|discourage|should not|minimize)\b/i, action: 'AVOID' }
+];
+
+/**
+ * Parse ADR markdown content into YAML-compatible standards object
+ *
+ * @param {string} content - Raw ADR markdown content
+ * @param {Object} options - Parser options
+ * @param {string} options.filename - Source filename for ID generation
+ * @param {string} options.category - Standards category (e.g., 'backend', 'database')
+ * @returns {Object} YAML-compatible standards object
+ */
+function parseAdr(content, options = {}) {
+  if (!content || typeof content !== 'string') {
+    throw new Error('ADR content is required and must be a string');
+  }
+
+  const filename = options.filename || 'unknown-adr';
+  const category = options.category || inferCategory(content);
+
+  const title = extractTitle(content);
+  const status = extractStatus(content);
+  const context = extractSection(content, 'Context');
+  const decision = extractSection(content, 'Decision');
+  const consequences = extractSection(content, 'Consequences');
+
+  const id = generateId(filename, title);
+  const rules = extractRules(decision);
+  const antiPatterns = extractAntiPatterns(consequences);
+  const priority = determinePriority(status, rules);
+
+  return {
+    id,
+    category,
+    priority,
+    rules,
+    anti_patterns: antiPatterns,
+    context: {
+      title,
+      status,
+      description: context || '',
+      source_format: 'adr',
+      source_file: filename
+    },
+    tags: extractTags(content, category),
+    updated: new Date().toISOString().split('T')[0]
+  };
+}
+
+/**
+ * Extract the ADR title from the first heading
+ *
+ * @param {string} content - ADR markdown content
+ * @returns {string} Extracted title
+ */
+function extractTitle(content) {
+  // ADR titles often follow pattern: "# ADR-NNN: Title" or "# Title"
+  const match = content.match(/^#\s+(?:ADR[-\s]?\d+[:\s-]+)?(.+)$/m);
+  return match ? match[1].trim() : 'Untitled ADR';
+}
+
+/**
+ * Extract the ADR status
+ *
+ * @param {string} content - ADR markdown content
+ * @returns {string} ADR status
+ */
+function extractStatus(content) {
+  const statusSection = extractSection(content, 'Status');
+  if (!statusSection) return 'proposed';
+
+  const statusMatch = statusSection.match(/\b(accepted|proposed|deprecated|superseded|rejected)\b/i);
+  return statusMatch ? statusMatch[1].toLowerCase() : 'proposed';
+}
+
+/**
+ * Extract a named section from ADR markdown
+ *
+ * @param {string} content - ADR markdown content
+ * @param {string} sectionName - Name of the section to extract
+ * @returns {string|null} Section content or null
+ */
+function extractSection(content, sectionName) {
+  // Split content by section headers and find the matching one
+  const sectionRegex = /^(##\s+.+)$/gm;
+  const headers = [];
+  let match;
+
+  while ((match = sectionRegex.exec(content)) !== null) {
+    headers.push({ text: match[1], index: match.index });
+  }
+
+  for (let i = 0; i < headers.length; i++) {
+    const headerText = headers[i].text.replace(/^##\s+/, '').trim();
+    if (headerText.toLowerCase() === sectionName.toLowerCase()) {
+      const startIndex = headers[i].index + headers[i].text.length;
+      const endIndex = (i + 1 < headers.length) ? headers[i + 1].index : content.length;
+      const sectionContent = content.substring(startIndex, endIndex).trim();
+      return sectionContent || null;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Extract rules from the Decision section
+ * Maps decision statements to YAML rules with action types
+ *
+ * @param {string} decisionText - Content of the Decision section
+ * @returns {Array<Object>} Array of rule objects with action and rule text
+ */
+function extractRules(decisionText) {
+  if (!decisionText) return [];
+
+  const rules = [];
+  const lines = decisionText.split('\n');
+
+  // Process list items and standalone sentences
+  const statements = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Capture bullet/numbered list items
+    const listMatch = trimmed.match(/^[-*\d]+\.?\s+(.+)$/);
+    if (listMatch) {
+      statements.push(listMatch[1].trim());
+      continue;
+    }
+
+    // Capture sentences that contain action keywords
+    if (trimmed.length > 15 && containsActionKeyword(trimmed)) {
+      statements.push(trimmed);
+    }
+  }
+
+  // Also split paragraph text into sentences for action keyword detection
+  const paragraphText = lines
+    .filter(l => !l.trim().match(/^[-*\d]+\./))
+    .join(' ')
+    .trim();
+
+  const sentences = paragraphText.split(/(?<=[.!])\s+/);
+  for (const sentence of sentences) {
+    const cleaned = sentence.trim();
+    if (cleaned.length > 15 && containsActionKeyword(cleaned)) {
+      // Avoid duplicates with list items
+      const isDuplicate = statements.some(s =>
+        s.includes(cleaned) || cleaned.includes(s)
+      );
+      if (!isDuplicate) {
+        statements.push(cleaned);
+      }
+    }
+  }
+
+  for (const statement of statements) {
+    const action = classifyAction(statement);
+    const ruleText = cleanRuleText(statement, action);
+
+    if (ruleText.length > 5) {
+      rules.push({
+        action,
+        rule: ruleText
+      });
+    }
+  }
+
+  // If no specific rules extracted, create a general USE rule from the decision
+  if (rules.length === 0 && decisionText.length > 20) {
+    const summary = decisionText.split('\n')[0].trim();
+    if (summary.length > 10) {
+      rules.push({
+        action: 'USE',
+        rule: summary.replace(/^We\s+(will|have decided to)\s+/i, '').trim()
+      });
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Extract anti-patterns from the Consequences section
+ * Negative consequences indicate what to avoid
+ *
+ * @param {string} consequencesText - Content of the Consequences section
+ * @returns {Array<string>} Array of anti-pattern descriptions
+ */
+function extractAntiPatterns(consequencesText) {
+  if (!consequencesText) return [];
+
+  const antiPatterns = [];
+  const lines = consequencesText.split('\n');
+
+  let inNegativeSection = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Detect negative subsection headers
+    if (trimmed.match(/^###?\s*(negative|bad|risks?|downsides?|drawbacks?|disadvantages?)/i)) {
+      inNegativeSection = true;
+      continue;
+    }
+
+    // Detect positive subsection headers (exit negative section)
+    if (trimmed.match(/^###?\s*(positive|good|benefits?|advantages?|upsides?)/i)) {
+      inNegativeSection = false;
+      continue;
+    }
+
+    // Detect neutral subsection headers
+    if (trimmed.match(/^###?\s*(neutral)/i)) {
+      inNegativeSection = false;
+      continue;
+    }
+
+    // Capture list items in negative sections
+    if (inNegativeSection) {
+      const listMatch = trimmed.match(/^[-*]\s+(.+)$/);
+      if (listMatch && listMatch[1].length > 10) {
+        antiPatterns.push(listMatch[1].trim());
+      }
+      continue;
+    }
+
+    // Capture items with negative markers anywhere in consequences
+    const negativeMatch = trimmed.match(/^[-*]\s*(?:(?:Bad|Negative|Risk|Downside)[:\s]+)?(.+)$/i);
+    if (negativeMatch) {
+      const item = negativeMatch[1].trim();
+      if (isNegativeConsequence(item)) {
+        antiPatterns.push(item);
+      }
+    }
+  }
+
+  return antiPatterns;
+}
+
+/**
+ * Check if a consequence line indicates a negative outcome
+ *
+ * @param {string} text - Consequence text
+ * @returns {boolean} True if the text describes a negative consequence
+ */
+function isNegativeConsequence(text) {
+  const negativeIndicators = [
+    /\brisk\b/i,
+    /\bcomplexity\b/i,
+    /\bdifficult\b/i,
+    /\boverhead\b/i,
+    /\bcost\b/i,
+    /\bslower\b/i,
+    /\blimitation\b/i,
+    /\bdrawback\b/i,
+    /\bdownside\b/i,
+    /\bchalleng/i,
+    /\bbreaking\b/i,
+    /\bmigration\b/i,
+    /\blearning curve\b/i,
+    /\bcoupling\b/i,
+    /\block-in\b/i,
+    /\btechnical debt\b/i,
+    /\bneed(?:s)?\s+to\b/i,
+    /\brequire(?:s)?\s+(?:additional|extra|more)\b/i
+  ];
+
+  return negativeIndicators.some(pattern => pattern.test(text));
+}
+
+/**
+ * Check if text contains an action keyword
+ *
+ * @param {string} text - Text to check
+ * @returns {boolean} True if text contains an action keyword
+ */
+function containsActionKeyword(text) {
+  return ACTION_PATTERNS.some(p => p.regex.test(text));
+}
+
+/**
+ * Classify the action type for a decision statement
+ *
+ * @param {string} statement - Decision statement
+ * @returns {string} Action type: ALWAYS, NEVER, USE, PREFER, or AVOID
+ */
+function classifyAction(statement) {
+  // Check NEVER before ALWAYS since "must not" contains "must"
+  for (const { regex, action } of ACTION_PATTERNS) {
+    if (action === 'NEVER' && regex.test(statement)) return 'NEVER';
+  }
+  for (const { regex, action } of ACTION_PATTERNS) {
+    if (action === 'AVOID' && regex.test(statement)) return 'AVOID';
+  }
+  for (const { regex, action } of ACTION_PATTERNS) {
+    if (action === 'ALWAYS' && regex.test(statement)) return 'ALWAYS';
+  }
+  for (const { regex, action } of ACTION_PATTERNS) {
+    if (action === 'PREFER' && regex.test(statement)) return 'PREFER';
+  }
+  for (const { regex, action } of ACTION_PATTERNS) {
+    if (action === 'USE' && regex.test(statement)) return 'USE';
+  }
+
+  return 'USE';
+}
+
+/**
+ * Clean rule text by removing leading action verbs for cleaner output
+ *
+ * @param {string} text - Raw rule text
+ * @param {string} action - Classified action type
+ * @returns {string} Cleaned rule text
+ */
+function cleanRuleText(text, action) {
+  let cleaned = text
+    .replace(/^We\s+(will|have decided to|decided to|should)\s+/i, '')
+    .replace(/^(Must|Shall|Always|Never|Should|Should not|Must not)\s+/i, '')
+    .replace(/\s*\.$/, '')
+    .trim();
+
+  // Capitalize first letter
+  if (cleaned.length > 0) {
+    cleaned = cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+  }
+
+  return cleaned;
+}
+
+/**
+ * Generate a standards-compatible ID from filename and title
+ *
+ * @param {string} filename - Source filename
+ * @param {string} title - ADR title
+ * @returns {string} Generated ID
+ */
+function generateId(filename, title) {
+  // Use filename slug if it looks like an ADR (e.g., "0001-use-react.md")
+  const filenameSlug = filename
+    .replace(/\.md$/i, '')
+    .replace(/[^a-z0-9]+/gi, '-')
+    .toLowerCase();
+
+  if (filenameSlug.match(/^\d+-/)) {
+    return `adr-${filenameSlug}`;
+  }
+
+  // Fall back to title-based ID
+  const titleSlug = title
+    .replace(/[^a-z0-9]+/gi, '-')
+    .toLowerCase()
+    .substring(0, 60);
+
+  return `adr-${titleSlug}`;
+}
+
+/**
+ * Infer category from ADR content
+ *
+ * @param {string} content - ADR markdown content
+ * @returns {string} Inferred category
+ */
+function inferCategory(content) {
+  const lower = content.toLowerCase();
+
+  const categoryKeywords = {
+    'serverless-saas-aws': ['lambda', 'api gateway', 'serverless', 'aws', 'sam template', 'cloudformation'],
+    'frontend-development': ['react', 'vue', 'angular', 'frontend', 'component', 'ui', 'css', 'tsx', 'jsx'],
+    'database': ['database', 'postgresql', 'sql', 'schema', 'migration', 'query', 'orm'],
+    'backend': ['api', 'service', 'handler', 'endpoint', 'rest', 'graphql'],
+    'multi-agent-orchestration': ['agent', 'orchestration', 'llm', 'ai', 'workflow'],
+    'compliance-security': ['security', 'authentication', 'authorization', 'encryption', 'compliance', 'audit'],
+    'cost-optimization': ['cost', 'performance', 'optimization', 'scaling', 'caching'],
+    'testing': ['test', 'testing', 'coverage', 'ci/cd', 'pipeline'],
+    'deployment': ['deploy', 'infrastructure', 'docker', 'kubernetes', 'ci/cd']
+  };
+
+  for (const [category, keywords] of Object.entries(categoryKeywords)) {
+    const matchCount = keywords.filter(kw => lower.includes(kw)).length;
+    if (matchCount >= 2) return category;
+  }
+
+  // Single keyword fallback
+  for (const [category, keywords] of Object.entries(categoryKeywords)) {
+    if (keywords.some(kw => lower.includes(kw))) return category;
+  }
+
+  return 'general';
+}
+
+/**
+ * Determine priority based on ADR status and rule types
+ * Priority values: 10 (high), 20 (medium), 30 (low)
+ *
+ * @param {string} status - ADR status
+ * @param {Array} rules - Extracted rules
+ * @returns {number} Priority value
+ */
+function determinePriority(status, rules) {
+  // Deprecated/superseded ADRs are low priority
+  if (status === 'deprecated' || status === 'superseded') return 30;
+
+  // If rules contain ALWAYS or NEVER, higher priority
+  const hasEnforcedRules = rules.some(r =>
+    r.action === 'ALWAYS' || r.action === 'NEVER'
+  );
+
+  if (hasEnforcedRules && status === 'accepted') return 10;
+  if (status === 'accepted') return 20;
+
+  return 30;
+}
+
+/**
+ * Extract relevant tags from ADR content
+ *
+ * @param {string} content - ADR content
+ * @param {string} category - Assigned category
+ * @returns {Array<string>} Tags
+ */
+function extractTags(content, category) {
+  const tags = ['adr', category];
+  const lower = content.toLowerCase();
+
+  const tagKeywords = {
+    'architecture': /\barchitectur/i,
+    'breaking-change': /\bbreaking\s+change/i,
+    'migration': /\bmigration/i,
+    'security': /\bsecurity\b/i,
+    'performance': /\bperformance\b/i,
+    'scalability': /\bscalability\b/i,
+    'maintainability': /\bmaintainability\b/i,
+    'testing': /\btesting\b/i
+  };
+
+  for (const [tag, pattern] of Object.entries(tagKeywords)) {
+    if (pattern.test(lower)) {
+      tags.push(tag);
+    }
+  }
+
+  return [...new Set(tags)];
+}
+
+module.exports = {
+  parseAdr,
+  extractTitle,
+  extractStatus,
+  extractSection,
+  extractRules,
+  extractAntiPatterns
+};