@equilateral_ai/mindmeld 3.5.2 → 4.0.1

package/src/core/parsers/adrParser.js

@@ -1,479 +0,0 @@
-/**
- * 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
-};