@equilateral_ai/mindmeld 3.2.0 → 3.3.0

package/src/core/parsers/cursorRulesParser.js

@@ -0,0 +1,564 @@
+/**
+ * Cursor Rules Parser - Parse AI coding assistant rule files into YAML standards format
+ *
+ * Supports:
+ *   - .cursorrules (Cursor IDE)
+ *   - CLAUDE.md (Claude Code)
+ *   - .windsurfrules (Windsurf IDE)
+ *   - Generic markdown rule files
+ *
+ * Extracts:
+ *   - Rules from sections with action headers (always, never, avoid, prefer, use)
+ *   - Banned patterns from "banned" or prohibition sections
+ *   - Implementation patterns from code blocks
+ *   - Trigger words and conventions
+ *
+ * Returns YAML-compatible object matching equilateral-standards schema
+ *
+ * @module parsers/cursorRulesParser
+ */
+
+/**
+ * Section header patterns that indicate rule types
+ */
+const SECTION_PATTERNS = {
+  ALWAYS: /\b(always|must|required|mandatory|enforce|critical)\b/i,
+  NEVER: /\b(never|banned|prohibited|forbidden|do not|don't)\b/i,
+  AVOID: /\b(avoid|discourage|anti-pattern|bad practice|don't use)\b/i,
+  PREFER: /\b(prefer|should|recommend|favor|better|best practice)\b/i,
+  USE: /\b(use|adopt|follow|implement|pattern|convention|standard)\b/i
+};
+
+/**
+ * Parse AI coding assistant rules file into YAML-compatible standards object
+ *
+ * @param {string} content - Raw markdown/text content of the rules file
+ * @param {Object} options - Parser options
+ * @param {string} options.filename - Source filename (e.g., '.cursorrules', 'CLAUDE.md')
+ * @param {string} options.category - Standards category override
+ * @returns {Object} YAML-compatible standards object
+ */
+function parseCursorRules(content, options = {}) {
+  if (!content || typeof content !== 'string') {
+    throw new Error('Rules file content is required and must be a string');
+  }
+
+  const filename = options.filename || 'rules';
+  const sourceFormat = detectSourceFormat(filename);
+
+  const sections = parseSections(content);
+  const rules = extractRules(sections, content);
+  const antiPatterns = extractAntiPatterns(sections, content);
+  const examples = extractCodeExamples(content);
+  const category = options.category || inferCategory(content);
+
+  const id = generateId(filename);
+
+  return {
+    id,
+    category,
+    priority: determinePriority(rules),
+    rules,
+    anti_patterns: antiPatterns,
+    context: {
+      source_format: sourceFormat,
+      source_file: filename,
+      examples,
+      description: extractDescription(content)
+    },
+    tags: extractTags(content, sourceFormat),
+    updated: new Date().toISOString().split('T')[0]
+  };
+}
+
+/**
+ * Detect the source format from filename
+ *
+ * @param {string} filename - Source filename
+ * @returns {string} Detected format identifier
+ */
+function detectSourceFormat(filename) {
+  const lower = filename.toLowerCase();
+  if (lower.includes('.cursorrules') || lower.includes('cursorrules')) return 'cursorrules';
+  if (lower.includes('claude.md') || lower.includes('claude')) return 'claude-md';
+  if (lower.includes('.windsurfrules') || lower.includes('windsurfrules')) return 'windsurfrules';
+  return 'markdown';
+}
+
+/**
+ * Parse content into structured sections based on headers
+ *
+ * @param {string} content - Markdown content
+ * @returns {Array<Object>} Array of section objects with heading, level, body, and action
+ */
+function parseSections(content) {
+  const sections = [];
+  const lines = content.split('\n');
+
+  let currentSection = null;
+  let bodyLines = [];
+
+  for (const line of lines) {
+    const headerMatch = line.match(/^(#{1,4})\s+(.+)$/);
+
+    if (headerMatch) {
+      // Save previous section
+      if (currentSection) {
+        currentSection.body = bodyLines.join('\n').trim();
+        sections.push(currentSection);
+      }
+
+      const heading = headerMatch[2].trim();
+      const level = headerMatch[1].length;
+      const action = classifySectionAction(heading);
+
+      currentSection = { heading, level, action, body: '' };
+      bodyLines = [];
+    } else {
+      bodyLines.push(line);
+    }
+  }
+
+  // Save final section
+  if (currentSection) {
+    currentSection.body = bodyLines.join('\n').trim();
+    sections.push(currentSection);
+  }
+
+  return sections;
+}
+
+/**
+ * Classify the action type for a section based on its heading
+ *
+ * @param {string} heading - Section heading text
+ * @returns {string|null} Action type or null if not a rule section
+ */
+function classifySectionAction(heading) {
+  // Check NEVER before ALWAYS since some headings might match both
+  if (SECTION_PATTERNS.NEVER.test(heading)) return 'NEVER';
+  if (SECTION_PATTERNS.AVOID.test(heading)) return 'AVOID';
+  if (SECTION_PATTERNS.ALWAYS.test(heading)) return 'ALWAYS';
+  if (SECTION_PATTERNS.PREFER.test(heading)) return 'PREFER';
+  if (SECTION_PATTERNS.USE.test(heading)) return 'USE';
+  return null;
+}
+
+/**
+ * Extract rules from parsed sections and raw content
+ *
+ * @param {Array<Object>} sections - Parsed sections
+ * @param {string} content - Raw content for fallback extraction
+ * @returns {Array<Object>} Array of rule objects with action and rule text
+ */
+function extractRules(sections, content) {
+  const rules = [];
+  const seenRules = new Set();
+
+  // Extract rules from classified sections
+  for (const section of sections) {
+    if (!section.action) continue;
+
+    const sectionRules = extractRulesFromBody(section.body, section.action);
+    for (const rule of sectionRules) {
+      const key = normalizeForDedup(rule.action, rule.rule);
+      if (!seenRules.has(key)) {
+        seenRules.add(key);
+        rules.push(rule);
+      }
+    }
+  }
+
+  // Extract inline rules from content (lines with action keywords)
+  const inlineRules = extractInlineRules(content);
+  for (const rule of inlineRules) {
+    const key = normalizeForDedup(rule.action, rule.rule);
+    if (!seenRules.has(key)) {
+      seenRules.add(key);
+      rules.push(rule);
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Extract rules from a section body
+ *
+ * @param {string} body - Section body text
+ * @param {string} defaultAction - Default action for rules in this section
+ * @returns {Array<Object>} Array of rule objects
+ */
+function extractRulesFromBody(body, defaultAction) {
+  if (!body) return [];
+
+  const rules = [];
+  const lines = body.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip empty lines, code block markers, and short lines
+    if (!trimmed || trimmed.startsWith('```') || trimmed.length < 10) continue;
+
+    // Skip lines that are inside code blocks
+    // (handled at a higher level by code block extraction)
+
+    // Extract list items
+    const listMatch = trimmed.match(/^[-*+]\s+(.+)$/);
+    if (listMatch) {
+      const ruleText = cleanRuleText(listMatch[1]);
+      if (ruleText.length >= 10) {
+        const action = detectInlineAction(ruleText) || defaultAction;
+        rules.push({
+          action,
+          rule: ruleText
+        });
+      }
+      continue;
+    }
+
+    // Extract numbered list items
+    const numberedMatch = trimmed.match(/^\d+\.?\s+(.+)$/);
+    if (numberedMatch) {
+      const ruleText = cleanRuleText(numberedMatch[1]);
+      if (ruleText.length >= 10) {
+        const action = detectInlineAction(ruleText) || defaultAction;
+        rules.push({
+          action,
+          rule: ruleText
+        });
+      }
+      continue;
+    }
+
+    // Extract bold statements as rules
+    const boldMatch = trimmed.match(/^\*\*(.+?)\*\*[:\s]*(.*)/);
+    if (boldMatch) {
+      const ruleText = cleanRuleText(`${boldMatch[1]}${boldMatch[2] ? ': ' + boldMatch[2] : ''}`);
+      if (ruleText.length >= 10) {
+        const action = detectInlineAction(ruleText) || defaultAction;
+        rules.push({
+          action,
+          rule: ruleText
+        });
+      }
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Extract rules that appear inline in content (not in classified sections)
+ * Looks for lines starting with action keywords
+ *
+ * @param {string} content - Raw content
+ * @returns {Array<Object>} Array of rule objects
+ */
+function extractInlineRules(content) {
+  const rules = [];
+  const lines = content.split('\n');
+
+  let inCodeBlock = false;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Track code blocks
+    if (trimmed.startsWith('```')) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+    if (inCodeBlock) continue;
+
+    // Match lines that start with action keywords
+    const actionMatch = trimmed.match(
+      /^[-*]?\s*\*?\*?(ALWAYS|NEVER|AVOID|PREFER|USE|DO NOT|DON'T)\*?\*?[:\s]+(.+)/i
+    );
+
+    if (actionMatch) {
+      const keyword = actionMatch[1].toUpperCase();
+      const ruleText = cleanRuleText(actionMatch[2]);
+
+      if (ruleText.length >= 10) {
+        let action;
+        if (keyword === 'ALWAYS') action = 'ALWAYS';
+        else if (keyword === 'NEVER' || keyword === 'DO NOT' || keyword === "DON'T") action = 'NEVER';
+        else if (keyword === 'AVOID') action = 'AVOID';
+        else if (keyword === 'PREFER') action = 'PREFER';
+        else action = 'USE';
+
+        rules.push({ action, rule: ruleText });
+      }
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Normalize a rule for deduplication by stripping action prefixes and lowercasing
+ *
+ * @param {string} action - Rule action type
+ * @param {string} ruleText - Rule text
+ * @returns {string} Normalized deduplication key
+ */
+function normalizeForDedup(action, ruleText) {
+  const normalized = ruleText
+    .toLowerCase()
+    .replace(/^(always|never|avoid|prefer|use|do not|don't|must not|shall not|must|shall|should)\s+/i, '')
+    .replace(/^(use|using|adopt|follow|implement)\s+/i, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return `${action}:${normalized}`;
+}
+
+/**
+ * Detect if a rule text contains an inline action keyword
+ *
+ * @param {string} text - Rule text
+ * @returns {string|null} Detected action or null
+ */
+function detectInlineAction(text) {
+  if (/^(?:never|do not|don't|must not|shall not)\b/i.test(text)) return 'NEVER';
+  if (/^(?:always|must|shall|required)\b/i.test(text)) return 'ALWAYS';
+  if (/^(?:avoid|discourage)\b/i.test(text)) return 'AVOID';
+  if (/^(?:prefer|should|recommend)\b/i.test(text)) return 'PREFER';
+  if (/^(?:use|adopt|follow)\b/i.test(text)) return 'USE';
+  return null;
+}
+
+/**
+ * Extract anti-patterns from sections and content
+ *
+ * @param {Array<Object>} sections - Parsed sections
+ * @param {string} content - Raw content
+ * @returns {Array<string>} Array of anti-pattern descriptions
+ */
+function extractAntiPatterns(sections, content) {
+  const antiPatterns = [];
+  const seen = new Set();
+
+  // Extract from NEVER and AVOID sections
+  for (const section of sections) {
+    if (section.action !== 'NEVER' && section.action !== 'AVOID') continue;
+
+    const lines = section.body.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      const listMatch = trimmed.match(/^[-*+]\s+(.+)$/);
+      if (listMatch && listMatch[1].length >= 10) {
+        const text = cleanRuleText(listMatch[1]);
+        if (!seen.has(text)) {
+          seen.add(text);
+          antiPatterns.push(text);
+        }
+      }
+    }
+  }
+
+  // Extract banned patterns from content
+  const bannedSection = content.match(/(?:^|\n)##?\s*(?:Banned|Prohibited|Forbidden)[^\n]*\n([\s\S]*?)(?=\n##?\s|\n*$)/i);
+  if (bannedSection) {
+    const lines = bannedSection[1].split('\n');
+    for (const line of lines) {
+      const listMatch = line.trim().match(/^[-*+]\s+(.+)$/);
+      if (listMatch && listMatch[1].length >= 10) {
+        const text = cleanRuleText(listMatch[1]);
+        if (!seen.has(text)) {
+          seen.add(text);
+          antiPatterns.push(text);
+        }
+      }
+    }
+  }
+
+  return antiPatterns;
+}
+
+/**
+ * Extract code examples from markdown code blocks
+ *
+ * @param {string} content - Raw markdown content
+ * @returns {Array<Object>} Array of example objects with language, code, and context
+ */
+function extractCodeExamples(content) {
+  const examples = [];
+  const codeBlockRegex = /```(\w+)?\n([\s\S]*?)```/g;
+
+  let match;
+  while ((match = codeBlockRegex.exec(content)) !== null) {
+    const language = match[1] || 'text';
+    const code = match[2].trim();
+
+    if (code.length < 5) continue;
+
+    // Get surrounding context (text before the code block)
+    const beforeBlock = content.substring(
+      Math.max(0, match.index - 200),
+      match.index
+    );
+    const contextMatch = beforeBlock.match(/([^\n]+)\n*$/);
+    const description = contextMatch ? contextMatch[1].trim() : '';
+
+    examples.push({
+      language,
+      code,
+      description: cleanRuleText(description) || 'Code example'
+    });
+  }
+
+  return examples;
+}
+
+/**
+ * Extract a brief description from the top of the content
+ *
+ * @param {string} content - Raw content
+ * @returns {string} Brief description
+ */
+function extractDescription(content) {
+  const lines = content.split('\n');
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    // Skip headers, empty lines, and code markers
+    if (!trimmed || trimmed.startsWith('#') || trimmed.startsWith('```')) continue;
+    // Skip list items
+    if (trimmed.match(/^[-*+\d]/)) continue;
+
+    if (trimmed.length >= 20) {
+      return trimmed.substring(0, 200);
+    }
+  }
+
+  return '';
+}
+
+/**
+ * Clean rule text by removing markdown formatting
+ *
+ * @param {string} text - Raw text
+ * @returns {string} Cleaned text
+ */
+function cleanRuleText(text) {
+  return text
+    .replace(/\*\*/g, '')         // Remove bold
+    .replace(/\*/g, '')           // Remove italic
+    .replace(/`([^`]+)`/g, '$1')  // Remove inline code markers
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')  // Replace links with text
+    .replace(/\s+/g, ' ')         // Normalize whitespace
+    .replace(/\s*\.$/, '')        // Remove trailing period
+    .trim();
+}
+
+/**
+ * Infer standards category from content
+ *
+ * @param {string} content - File content
+ * @returns {string} Inferred category
+ */
+function inferCategory(content) {
+  const lower = content.toLowerCase();
+
+  const categoryKeywords = {
+    'serverless-saas-aws': ['lambda', 'aws', 'serverless', 'sam', 'cloudformation', 'api gateway'],
+    'frontend-development': ['react', 'vue', 'angular', 'component', 'css', 'tsx', 'jsx', 'frontend', 'ui'],
+    'database': ['database', 'sql', 'postgresql', 'schema', 'migration', 'query'],
+    'backend': ['api', 'handler', 'endpoint', 'express', 'node.js', 'server'],
+    'multi-agent-orchestration': ['agent', 'orchestration', 'llm', 'prompt', 'ai assistant'],
+    'compliance-security': ['security', 'auth', 'encryption', 'compliance', 'vulnerability'],
+    'testing': ['test', 'jest', 'mocha', 'coverage', 'assertion'],
+    'deployment': ['deploy', 'ci/cd', 'pipeline', 'docker', 'kubernetes']
+  };
+
+  let bestCategory = 'general';
+  let bestScore = 0;
+
+  for (const [category, keywords] of Object.entries(categoryKeywords)) {
+    const score = keywords.filter(kw => lower.includes(kw)).length;
+    if (score > bestScore) {
+      bestScore = score;
+      bestCategory = category;
+    }
+  }
+
+  return bestCategory;
+}
+
+/**
+ * Generate standards ID from filename
+ *
+ * @param {string} filename - Source filename
+ * @returns {string} Generated ID
+ */
+function generateId(filename) {
+  const slug = filename
+    .replace(/^\./g, '')
+    .replace(/\.(md|txt|json)$/i, '')
+    .replace(/[^a-z0-9]+/gi, '-')
+    .toLowerCase();
+
+  return `rules-${slug}`;
+}
+
+/**
+ * Determine priority based on rule distribution
+ *
+ * @param {Array<Object>} rules - Extracted rules
+ * @returns {number} Priority (10, 20, or 30)
+ */
+function determinePriority(rules) {
+  if (rules.length === 0) return 30;
+
+  const enforcedCount = rules.filter(r =>
+    r.action === 'ALWAYS' || r.action === 'NEVER'
+  ).length;
+
+  if (enforcedCount / rules.length > 0.5) return 10;
+  if (enforcedCount > 0) return 20;
+  return 30;
+}
+
+/**
+ * Extract tags from content and source format
+ *
+ * @param {string} content - File content
+ * @param {string} sourceFormat - Detected source format
+ * @returns {Array<string>} Tags
+ */
+function extractTags(content, sourceFormat) {
+  const tags = [sourceFormat, 'ai-rules'];
+
+  const lower = content.toLowerCase();
+
+  const tagKeywords = {
+    'code-style': /\b(style|formatting|naming|convention)\b/i,
+    'architecture': /\barchitectur/i,
+    'security': /\bsecurity\b/i,
+    'performance': /\bperformance\b/i,
+    'testing': /\btesting\b/i,
+    'documentation': /\bdocument/i,
+    'error-handling': /\berror.?handling\b/i,
+    'typescript': /\btypescript\b/i,
+    'react': /\breact\b/i,
+    'node': /\bnode\.?js\b/i
+  };
+
+  for (const [tag, pattern] of Object.entries(tagKeywords)) {
+    if (pattern.test(lower)) {
+      tags.push(tag);
+    }
+  }
+
+  return [...new Set(tags)];
+}
+
+module.exports = {
+  parseCursorRules,
+  parseSections,
+  extractRules,
+  extractAntiPatterns,
+  extractCodeExamples
+};