@girardmedia/bootspring 2.0.37 → 2.0.38

package/core/coherence/semantic-analyzer.js

@@ -0,0 +1,836 @@
+/**
+ * Semantic Document Analyzer
+ *
+ * AI-powered document understanding for extracting concepts,
+ * analyzing terminology, finding contradictions, measuring
+ * specificity, detecting gaps, and validating cross-references.
+ *
+ * @package bootspring
+ * @module core/coherence/semantic-analyzer
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+
+/**
+ * Common technical terms to track
+ */
+const TECHNICAL_TERMS = [
+  'api', 'database', 'authentication', 'authorization', 'cache',
+  'component', 'service', 'model', 'controller', 'middleware',
+  'endpoint', 'route', 'schema', 'migration', 'deployment',
+  'testing', 'integration', 'unit test', 'e2e', 'ci/cd',
+  'microservice', 'monolith', 'serverless', 'container'
+];
+
+/**
+ * Vague language patterns
+ */
+const VAGUE_PATTERNS = [
+  { pattern: /\b(various|several|some|many|few)\s+\w+s?\b/gi, type: 'quantity' },
+  { pattern: /\b(soon|later|eventually|sometime)\b/gi, type: 'timeline' },
+  { pattern: /\b(might|could|may|possibly|perhaps)\b/gi, type: 'uncertainty' },
+  { pattern: /\b(good|better|best|nice|great)\b/gi, type: 'subjective' },
+  { pattern: /\b(etc|and so on|and more|things like)\b/gi, type: 'incomplete' }
+];
+
+/**
+ * Concrete language patterns
+ */
+const CONCRETE_PATTERNS = [
+  { pattern: /\d+\s*(ms|seconds?|minutes?|hours?|days?|weeks?|months?)/gi, type: 'duration' },
+  { pattern: /\d+(\.\d+)?%/g, type: 'percentage' },
+  { pattern: /\$[\d,]+(\.\d{2})?/g, type: 'currency' },
+  { pattern: /\b\d{4}-\d{2}-\d{2}\b/g, type: 'date' },
+  { pattern: /v?\d+\.\d+(\.\d+)?/g, type: 'version' },
+  { pattern: /\b(must|shall|will|requires?)\b/gi, type: 'requirement' }
+];
+
+/**
+ * SemanticDocumentAnalyzer class
+ */
+class SemanticDocumentAnalyzer {
+  /**
+   * @param {Object} options - Configuration options
+   */
+  constructor(options = {}) {
+    this.projectRoot = options.projectRoot || process.cwd();
+    this.planningDir = options.planningDir || path.join(this.projectRoot, 'planning');
+  }
+
+  /**
+   * Analyze all documents
+   * @param {Object} documents - Map of document name to content
+   */
+  async analyze(documents) {
+    const analysis = {
+      concepts: await this.extractConcepts(documents),
+      terminology: await this.analyzeTerminology(documents),
+      contradictions: await this.findContradictions(documents),
+      specificity: await this.measureSpecificity(documents),
+      gaps: await this.detectGaps(documents),
+      crossReferences: await this.validateReferences(documents),
+      summary: null
+    };
+
+    // Generate summary
+    analysis.summary = this.generateSummary(analysis);
+
+    return analysis;
+  }
+
+  /**
+   * Load documents from planning directory
+   */
+  async loadDocuments() {
+    const documents = {};
+
+    try {
+      const files = await fs.readdir(this.planningDir);
+      const mdFiles = files.filter(f => f.endsWith('.md'));
+
+      for (const file of mdFiles) {
+        const filePath = path.join(this.planningDir, file);
+        const content = await fs.readFile(filePath, 'utf-8');
+        const docName = file.replace('.md', '').toLowerCase();
+        documents[docName] = content;
+      }
+    } catch {
+      // Planning directory doesn't exist
+    }
+
+    return documents;
+  }
+
+  /**
+   * Extract core concepts from documents
+   * @param {Object} documents - Map of document name to content
+   */
+  async extractConcepts(documents) {
+    const concepts = {};
+    const allContent = Object.values(documents).join('\n');
+
+    // Extract technical terms
+    for (const term of TECHNICAL_TERMS) {
+      const regex = new RegExp(`\\b${term}\\b`, 'gi');
+      const matches = allContent.match(regex) || [];
+
+      if (matches.length > 0) {
+        concepts[term] = {
+          frequency: matches.length,
+          documents: this.findDocumentsContaining(documents, term)
+        };
+      }
+    }
+
+    // Extract capitalized terms (likely domain concepts)
+    const capitalizedRegex = /\b[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*\b/g;
+    const capitalizedMatches = allContent.match(capitalizedRegex) || [];
+
+    const domainConcepts = {};
+    for (const match of capitalizedMatches) {
+      // Filter out common words
+      if (this.isLikelyDomainConcept(match)) {
+        domainConcepts[match] = (domainConcepts[match] || 0) + 1;
+      }
+    }
+
+    // Get top domain concepts
+    const topDomainConcepts = Object.entries(domainConcepts)
+      .filter(([, count]) => count >= 2)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 20)
+      .map(([term, count]) => ({
+        term,
+        frequency: count,
+        documents: this.findDocumentsContaining(documents, term)
+      }));
+
+    return {
+      technical: concepts,
+      domain: topDomainConcepts,
+      totalUniqueConcepts: Object.keys(concepts).length + topDomainConcepts.length
+    };
+  }
+
+  /**
+   * Check if term is likely a domain concept
+   * @param {string} term - Term to check
+   */
+  isLikelyDomainConcept(term) {
+    const commonWords = new Set([
+      'The', 'This', 'That', 'These', 'Those', 'When', 'Where', 'What',
+      'How', 'Why', 'Which', 'Who', 'For', 'With', 'From', 'Into',
+      'About', 'After', 'Before', 'Between', 'During', 'Without',
+      'Through', 'Against', 'Within', 'Among', 'However', 'Therefore',
+      'Furthermore', 'Additionally', 'Moreover', 'Finally', 'First',
+      'Second', 'Third', 'Next', 'Last', 'Also', 'Only', 'Just',
+      'Now', 'Then', 'Here', 'There', 'Each', 'Every', 'Some',
+      'Any', 'Most', 'Many', 'Few', 'All', 'Both', 'Either', 'Neither'
+    ]);
+
+    return !commonWords.has(term) && term.length > 2;
+  }
+
+  /**
+   * Find documents containing a term
+   * @param {Object} documents - Map of document name to content
+   * @param {string} term - Term to search for
+   */
+  findDocumentsContaining(documents, term) {
+    const result = [];
+    const regex = new RegExp(`\\b${term}\\b`, 'gi');
+
+    for (const [docName, content] of Object.entries(documents)) {
+      if (regex.test(content)) {
+        result.push(docName);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Analyze terminology consistency
+   * @param {Object} documents - Map of document name to content
+   */
+  async analyzeTerminology(documents) {
+    const terms = {};
+    const inconsistencies = [];
+
+    // Extract term definitions and usages
+    for (const [docName, content] of Object.entries(documents)) {
+      const extracted = this.extractTermDefinitions(content);
+
+      for (const term of extracted) {
+        if (!terms[term.name]) {
+          terms[term.name] = { usages: [] };
+        }
+
+        terms[term.name].usages.push({
+          document: docName,
+          context: term.context,
+          definition: term.definition
+        });
+      }
+    }
+
+    // Find inconsistencies
+    for (const [termName, termData] of Object.entries(terms)) {
+      if (termData.usages.length > 1) {
+        const definitions = termData.usages
+          .map(u => u.definition)
+          .filter(Boolean);
+
+        if (definitions.length > 1) {
+          // Check if definitions are similar
+          const unique = [...new Set(definitions.map(d => d.toLowerCase().trim()))];
+          if (unique.length > 1) {
+            inconsistencies.push({
+              term: termName,
+              issue: 'Inconsistent definitions across documents',
+              usages: termData.usages.map(u => ({
+                document: u.document,
+                definition: u.definition
+              }))
+            });
+          }
+        }
+      }
+    }
+
+    return {
+      terms: Object.keys(terms).length,
+      documented: Object.values(terms).filter(t =>
+        t.usages.some(u => u.definition)
+      ).length,
+      inconsistencies
+    };
+  }
+
+  /**
+   * Extract term definitions from content
+   * @param {string} content - Document content
+   */
+  extractTermDefinitions(content) {
+    const terms = [];
+
+    // Pattern: "Term: definition" or "**Term**: definition"
+    const definitionPattern = /(?:\*\*)?([A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)(?:\*\*)?:\s*([^.\n]+\.?)/g;
+    let match;
+
+    while ((match = definitionPattern.exec(content)) !== null) {
+      terms.push({
+        name: match[1].trim(),
+        definition: match[2].trim(),
+        context: this.getContext(content, match.index)
+      });
+    }
+
+    // Pattern: "Term is/are definition"
+    const isPattern = /([A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)\s+(?:is|are)\s+([^.\n]+\.)/g;
+
+    while ((match = isPattern.exec(content)) !== null) {
+      if (!terms.find(t => t.name === match[1].trim())) {
+        terms.push({
+          name: match[1].trim(),
+          definition: match[2].trim(),
+          context: this.getContext(content, match.index)
+        });
+      }
+    }
+
+    return terms;
+  }
+
+  /**
+   * Get surrounding context for a match
+   * @param {string} content - Full content
+   * @param {number} index - Match index
+   */
+  getContext(content, index) {
+    const start = Math.max(0, index - 50);
+    const end = Math.min(content.length, index + 100);
+    return content.slice(start, end).replace(/\n/g, ' ').trim();
+  }
+
+  /**
+   * Find contradictions between documents
+   * @param {Object} documents - Map of document name to content
+   */
+  async findContradictions(documents) {
+    const contradictions = [];
+
+    // Check for conflicting statements
+    const statements = this.extractStatements(documents);
+
+    // Group by topic
+    const topicGroups = {};
+    for (const statement of statements) {
+      const topic = this.extractTopic(statement.text);
+      if (topic) {
+        if (!topicGroups[topic]) {
+          topicGroups[topic] = [];
+        }
+        topicGroups[topic].push(statement);
+      }
+    }
+
+    // Find conflicts within topic groups
+    for (const [topic, stmts] of Object.entries(topicGroups)) {
+      if (stmts.length > 1) {
+        const conflicts = this.findConflicts(stmts);
+        contradictions.push(...conflicts);
+      }
+    }
+
+    // Check for timeline contradictions
+    const timelineConflicts = this.findTimelineConflicts(documents);
+    contradictions.push(...timelineConflicts);
+
+    return contradictions;
+  }
+
+  /**
+   * Extract factual statements from documents
+   * @param {Object} documents - Map of document name to content
+   */
+  extractStatements(documents) {
+    const statements = [];
+
+    for (const [docName, content] of Object.entries(documents)) {
+      // Extract sentences with factual indicators
+      const sentences = content.split(/[.!?]+/).filter(s => s.trim());
+
+      for (const sentence of sentences) {
+        const trimmed = sentence.trim();
+        if (this.isFactualStatement(trimmed)) {
+          statements.push({
+            text: trimmed,
+            document: docName
+          });
+        }
+      }
+    }
+
+    return statements;
+  }
+
+  /**
+   * Check if sentence is a factual statement
+   * @param {string} sentence - Sentence to check
+   */
+  isFactualStatement(sentence) {
+    const factualIndicators = /\b(is|are|will|must|shall|requires?|uses?|supports?|provides?|enables?)\b/i;
+    const minLength = 20;
+
+    return sentence.length >= minLength && factualIndicators.test(sentence);
+  }
+
+  /**
+   * Extract main topic from statement
+   * @param {string} text - Statement text
+   */
+  extractTopic(text) {
+    // Extract subject (first noun phrase)
+    const match = text.match(/^(?:The\s+)?([A-Za-z]+(?:\s+[A-Za-z]+)?)/i);
+    return match ? match[1].toLowerCase() : null;
+  }
+
+  /**
+   * Find conflicts between statements
+   * @param {Array} statements - Statements on same topic
+   */
+  findConflicts(statements) {
+    const conflicts = [];
+
+    // Compare each pair
+    for (let i = 0; i < statements.length; i++) {
+      for (let j = i + 1; j < statements.length; j++) {
+        const conflict = this.detectConflict(statements[i], statements[j]);
+        if (conflict) {
+          conflicts.push(conflict);
+        }
+      }
+    }
+
+    return conflicts;
+  }
+
+  /**
+   * Detect if two statements conflict
+   * @param {Object} stmt1 - First statement
+   * @param {Object} stmt2 - Second statement
+   */
+  detectConflict(stmt1, stmt2) {
+    const text1 = stmt1.text.toLowerCase();
+    const text2 = stmt2.text.toLowerCase();
+
+    // Check for negation conflicts
+    const negations = ['not', "n't", 'never', 'no', 'none', 'without'];
+    const hasNegation1 = negations.some(n => text1.includes(n));
+    const hasNegation2 = negations.some(n => text2.includes(n));
+
+    // If one has negation and they share key terms, possible conflict
+    if (hasNegation1 !== hasNegation2) {
+      const words1 = new Set(text1.match(/\b\w{4,}\b/g) || []);
+      const words2 = new Set(text2.match(/\b\w{4,}\b/g) || []);
+      const overlap = [...words1].filter(w => words2.has(w));
+
+      if (overlap.length >= 3) {
+        return {
+          type: 'negation',
+          severity: 'medium',
+          statements: [
+            { document: stmt1.document, text: stmt1.text.slice(0, 100) },
+            { document: stmt2.document, text: stmt2.text.slice(0, 100) }
+          ],
+          sharedTerms: overlap.slice(0, 5)
+        };
+      }
+    }
+
+    // Check for numeric conflicts
+    const nums1 = text1.match(/\d+/g) || [];
+    const nums2 = text2.match(/\d+/g) || [];
+
+    if (nums1.length > 0 && nums2.length > 0) {
+      // Extract what the numbers refer to
+      const context1 = text1.replace(/\d+/g, 'NUM').slice(0, 50);
+      const context2 = text2.replace(/\d+/g, 'NUM').slice(0, 50);
+
+      if (this.contextSimilarity(context1, context2) > 0.6 && nums1[0] !== nums2[0]) {
+        return {
+          type: 'numeric',
+          severity: 'high',
+          statements: [
+            { document: stmt1.document, text: stmt1.text.slice(0, 100), value: nums1[0] },
+            { document: stmt2.document, text: stmt2.text.slice(0, 100), value: nums2[0] }
+          ]
+        };
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Calculate simple context similarity
+   * @param {string} ctx1 - First context
+   * @param {string} ctx2 - Second context
+   */
+  contextSimilarity(ctx1, ctx2) {
+    const words1 = new Set(ctx1.toLowerCase().split(/\s+/));
+    const words2 = new Set(ctx2.toLowerCase().split(/\s+/));
+    const intersection = [...words1].filter(w => words2.has(w));
+    const union = new Set([...words1, ...words2]);
+
+    return intersection.length / union.size;
+  }
+
+  /**
+   * Find timeline conflicts
+   * @param {Object} documents - Map of document name to content
+   */
+  findTimelineConflicts(documents) {
+    const conflicts = [];
+    const timelines = {};
+
+    // Extract timeline mentions
+    for (const [docName, content] of Object.entries(documents)) {
+      const dateMatches = content.matchAll(/(\w+\s+\d{4}|\d{4}-\d{2}(?:-\d{2})?|Q[1-4]\s+\d{4})/gi);
+
+      for (const match of dateMatches) {
+        const context = this.getContext(content, match.index);
+        const topic = this.extractTopic(context);
+
+        if (topic) {
+          if (!timelines[topic]) {
+            timelines[topic] = [];
+          }
+          timelines[topic].push({
+            document: docName,
+            date: match[0],
+            context
+          });
+        }
+      }
+    }
+
+    // Find conflicts
+    for (const [topic, entries] of Object.entries(timelines)) {
+      if (entries.length > 1) {
+        const dates = entries.map(e => e.date);
+        const uniqueDates = [...new Set(dates)];
+
+        if (uniqueDates.length > 1) {
+          conflicts.push({
+            type: 'timeline',
+            topic,
+            severity: 'medium',
+            entries: entries.map(e => ({
+              document: e.document,
+              date: e.date
+            }))
+          });
+        }
+      }
+    }
+
+    return conflicts;
+  }
+
+  /**
+   * Measure document specificity
+   * @param {Object} documents - Map of document name to content
+   */
+  async measureSpecificity(documents) {
+    const results = {};
+    let totalVague = 0;
+    let totalConcrete = 0;
+    let totalWords = 0;
+
+    for (const [docName, content] of Object.entries(documents)) {
+      const docResult = this.measureDocumentSpecificity(content);
+      results[docName] = docResult;
+
+      totalVague += docResult.vagueCount;
+      totalConcrete += docResult.concreteCount;
+      totalWords += docResult.wordCount;
+    }
+
+    // Calculate overall score (0-100)
+    const vagueRatio = totalVague / Math.max(totalWords, 1);
+    const concreteRatio = totalConcrete / Math.max(totalWords, 1);
+    const score = Math.round((1 - vagueRatio + concreteRatio) * 50);
+
+    return {
+      byDocument: results,
+      overall: {
+        score: Math.min(100, Math.max(0, score)),
+        vagueTerms: totalVague,
+        concreteTerms: totalConcrete,
+        rating: score >= 70 ? 'specific' : score >= 50 ? 'moderate' : 'vague'
+      }
+    };
+  }
+
+  /**
+   * Measure specificity of a single document
+   * @param {string} content - Document content
+   */
+  measureDocumentSpecificity(content) {
+    let vagueCount = 0;
+    let concreteCount = 0;
+    const vagueExamples = [];
+    const concreteExamples = [];
+
+    // Count vague patterns
+    for (const { pattern, type } of VAGUE_PATTERNS) {
+      const matches = content.match(pattern) || [];
+      vagueCount += matches.length;
+      if (matches.length > 0 && vagueExamples.length < 5) {
+        vagueExamples.push({ type, example: matches[0] });
+      }
+    }
+
+    // Count concrete patterns
+    for (const { pattern, type } of CONCRETE_PATTERNS) {
+      const matches = content.match(pattern) || [];
+      concreteCount += matches.length;
+      if (matches.length > 0 && concreteExamples.length < 5) {
+        concreteExamples.push({ type, example: matches[0] });
+      }
+    }
+
+    const wordCount = (content.match(/\b\w+\b/g) || []).length;
+
+    return {
+      wordCount,
+      vagueCount,
+      concreteCount,
+      vagueExamples,
+      concreteExamples,
+      ratio: vagueCount / Math.max(concreteCount, 1)
+    };
+  }
+
+  /**
+   * Detect gaps in documentation
+   * @param {Object} documents - Map of document name to content
+   */
+  async detectGaps(documents) {
+    const gaps = {
+      mentionedButNotDefined: [],
+      referencedDocuments: [],
+      missingDetails: []
+    };
+
+    const allContent = Object.values(documents).join('\n');
+
+    // Find terms mentioned but not defined
+    const mentionedTerms = this.extractMentionedConcepts(allContent);
+    const definedTerms = new Set(
+      Object.values(documents)
+        .flatMap(content => this.extractTermDefinitions(content))
+        .map(t => t.name.toLowerCase())
+    );
+
+    for (const term of mentionedTerms) {
+      if (!definedTerms.has(term.toLowerCase())) {
+        gaps.mentionedButNotDefined.push(term);
+      }
+    }
+
+    // Find referenced documents that don't exist
+    const docReferences = allContent.match(/see\s+([A-Z][A-Z_]+)\.md|refer\s+to\s+([A-Z][A-Z_]+)/gi) || [];
+    const existingDocs = new Set(Object.keys(documents).map(d => d.toLowerCase()));
+
+    for (const ref of docReferences) {
+      const docName = ref.match(/([A-Z][A-Z_]+)/i)?.[1]?.toLowerCase();
+      if (docName && !existingDocs.has(docName)) {
+        gaps.referencedDocuments.push(docName);
+      }
+    }
+
+    // Find sections with TODO or TBD
+    const todoPattern = /(?:TODO|TBD|FIXME|XXX|WIP)[\s:]+([^\n]+)/gi;
+    let match;
+    while ((match = todoPattern.exec(allContent)) !== null) {
+      gaps.missingDetails.push({
+        type: match[0].split(/[\s:]/)[0],
+        detail: match[1].trim().slice(0, 100)
+      });
+    }
+
+    // Limit results
+    gaps.mentionedButNotDefined = [...new Set(gaps.mentionedButNotDefined)].slice(0, 10);
+    gaps.referencedDocuments = [...new Set(gaps.referencedDocuments)];
+    gaps.missingDetails = gaps.missingDetails.slice(0, 10);
+
+    return gaps;
+  }
+
+  /**
+   * Extract concepts that are mentioned but might need definition
+   * @param {string} content - Content to analyze
+   */
+  extractMentionedConcepts(content) {
+    const concepts = [];
+
+    // Look for capitalized terms followed by specific indicators
+    const needsDefinitionPattern = /(?:the\s+)?([A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)\s+(?:should|must|will|needs?|requires?)/gi;
+    let match;
+
+    while ((match = needsDefinitionPattern.exec(content)) !== null) {
+      if (this.isLikelyDomainConcept(match[1])) {
+        concepts.push(match[1]);
+      }
+    }
+
+    return concepts;
+  }
+
+  /**
+   * Validate cross-references between documents
+   * @param {Object} documents - Map of document name to content
+   */
+  async validateReferences(documents) {
+    const references = {
+      valid: [],
+      broken: [],
+      suggestions: []
+    };
+
+    const docNames = Object.keys(documents);
+
+    for (const [docName, content] of Object.entries(documents)) {
+      // Find links to other documents
+      const linkPattern = /\[([^\]]+)\]\(([^)]+)\)|see\s+([A-Z][A-Z_]+\.md)/gi;
+      let match;
+
+      while ((match = linkPattern.exec(content)) !== null) {
+        const target = match[2] || match[3];
+
+        if (target && target.endsWith('.md')) {
+          const targetName = target.replace('.md', '').toLowerCase();
+          const exists = docNames.includes(targetName);
+
+          if (exists) {
+            references.valid.push({
+              from: docName,
+              to: targetName,
+              text: match[1] || target
+            });
+          } else {
+            references.broken.push({
+              from: docName,
+              to: targetName,
+              suggestion: this.findSimilarDoc(targetName, docNames)
+            });
+          }
+        }
+      }
+
+      // Find implicit references
+      for (const otherDoc of docNames) {
+        if (otherDoc !== docName) {
+          const regex = new RegExp(`\\b${otherDoc}\\b`, 'gi');
+          if (regex.test(content)) {
+            references.suggestions.push({
+              from: docName,
+              to: otherDoc,
+              suggestion: `Consider adding explicit link to ${otherDoc.toUpperCase()}.md`
+            });
+          }
+        }
+      }
+    }
+
+    // Deduplicate suggestions
+    references.suggestions = references.suggestions.filter((s, i, arr) =>
+      arr.findIndex(x => x.from === s.from && x.to === s.to) === i
+    ).slice(0, 10);
+
+    return references;
+  }
+
+  /**
+   * Find similar document name
+   * @param {string} name - Document name to match
+   * @param {Array} docNames - Available document names
+   */
+  findSimilarDoc(name, docNames) {
+    for (const doc of docNames) {
+      if (doc.includes(name) || name.includes(doc)) {
+        return `Did you mean ${doc.toUpperCase()}.md?`;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Generate analysis summary
+   * @param {Object} analysis - Full analysis results
+   */
+  generateSummary(analysis) {
+    const issues = [];
+
+    // Terminology issues
+    if (analysis.terminology.inconsistencies.length > 0) {
+      issues.push({
+        type: 'terminology',
+        severity: 'medium',
+        count: analysis.terminology.inconsistencies.length,
+        message: `${analysis.terminology.inconsistencies.length} terminology inconsistencies found`
+      });
+    }
+
+    // Contradictions
+    if (analysis.contradictions.length > 0) {
+      issues.push({
+        type: 'contradiction',
+        severity: 'high',
+        count: analysis.contradictions.length,
+        message: `${analysis.contradictions.length} potential contradictions found`
+      });
+    }
+
+    // Specificity
+    if (analysis.specificity.overall.rating === 'vague') {
+      issues.push({
+        type: 'specificity',
+        severity: 'medium',
+        count: analysis.specificity.overall.vagueTerms,
+        message: 'Documents contain excessive vague language'
+      });
+    }
+
+    // Gaps
+    const totalGaps = analysis.gaps.mentionedButNotDefined.length +
+                      analysis.gaps.referencedDocuments.length +
+                      analysis.gaps.missingDetails.length;
+    if (totalGaps > 0) {
+      issues.push({
+        type: 'gaps',
+        severity: 'low',
+        count: totalGaps,
+        message: `${totalGaps} documentation gaps detected`
+      });
+    }
+
+    // Broken references
+    if (analysis.crossReferences.broken.length > 0) {
+      issues.push({
+        type: 'references',
+        severity: 'medium',
+        count: analysis.crossReferences.broken.length,
+        message: `${analysis.crossReferences.broken.length} broken document references`
+      });
+    }
+
+    // Calculate overall health score
+    let score = 100;
+    for (const issue of issues) {
+      if (issue.severity === 'high') score -= issue.count * 15;
+      else if (issue.severity === 'medium') score -= issue.count * 8;
+      else score -= issue.count * 3;
+    }
+    score = Math.max(0, Math.min(100, score));
+
+    return {
+      score,
+      rating: score >= 80 ? 'good' : score >= 60 ? 'fair' : 'needs improvement',
+      issues,
+      conceptCount: analysis.concepts.totalUniqueConcepts,
+      documentedTerms: analysis.terminology.documented
+    };
+  }
+}
+
+module.exports = {
+  SemanticDocumentAnalyzer,
+  TECHNICAL_TERMS,
+  VAGUE_PATTERNS,
+  CONCRETE_PATTERNS
+};