devforgeai 1.0.4 → 1.0.6

package/src/claude/scripts/devforgeai_cli/utils/markdown_parser.py

@@ -0,0 +1,219 @@
+#!/usr/bin/env python3
+"""
+Markdown Parser for DevForgeAI Story Files
+
+Extracts sections, checklists, and content from markdown documents.
+Pattern based on industry research (SpecDriven AI, GitHub DoD Checker).
+"""
+
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+
+def extract_section(content: str, section_name: str) -> Optional[str]:
+    """
+    Extract a section from markdown content.
+
+    Args:
+        content: Full markdown content
+        section_name: Section header (without ## prefix)
+
+    Returns:
+        Section content (excluding header) or None if not found
+
+    Example:
+        >>> content = "## Introduction\\nText\\n## Details\\nMore text"
+        >>> extract_section(content, "Details")
+        'More text'
+    """
+    # Match section: ## {name} until next ## or end of file
+    pattern = rf'^## {re.escape(section_name)}\s*\n(.*?)(?:\n##|\Z)'
+    match = re.search(pattern, content, re.MULTILINE | re.DOTALL)
+
+    if match:
+        return match.group(1).strip()
+    return None
+
+
+def parse_checklist(section_content: str) -> List[Dict[str, Any]]:
+    """
+    Parse markdown checklist items from section content.
+
+    Args:
+        section_content: Content of a section containing checklist items
+
+    Returns:
+        List of dicts with: text, checked, line_number
+
+    Example:
+        >>> content = "- [x] Complete item\\n- [ ] Incomplete item"
+        >>> parse_checklist(content)
+        [
+            {'text': 'Complete item', 'checked': True, 'line_number': 1},
+            {'text': 'Incomplete item', 'checked': False, 'line_number': 2}
+        ]
+    """
+    items = []
+
+    # Match: - [x] or - [ ] followed by text
+    pattern = r'^-\s*\[([ x])\]\s*(.+)$'
+
+    for line_num, line in enumerate(section_content.split('\n'), start=1):
+        match = re.match(pattern, line.strip())
+        if match:
+            checkbox_char = match.group(1)
+            item_text = match.group(2).strip()
+
+            items.append({
+                'text': item_text,
+                'checked': checkbox_char == 'x',
+                'line_number': line_num,
+                'raw_line': line
+            })
+
+    return items
+
+
+def extract_all_sections(content: str) -> Dict[str, str]:
+    """
+    Extract all ## sections from markdown.
+
+    Args:
+        content: Full markdown content
+
+    Returns:
+        Dict mapping section names to section content
+    """
+    sections = {}
+
+    # Find all ## headers
+    pattern = r'^## (.+?)\s*$'
+    matches = list(re.finditer(pattern, content, re.MULTILINE))
+
+    for i, match in enumerate(matches):
+        section_name = match.group(1).strip()
+        start = match.end()
+
+        # End is next section or end of file
+        if i + 1 < len(matches):
+            end = matches[i + 1].start()
+        else:
+            end = len(content)
+
+        section_content = content[start:end].strip()
+        sections[section_name] = section_content
+
+    return sections
+
+
+def find_checklist_item_context(content: str, item_text: str, context_lines: int = 3) -> Optional[str]:
+    """
+    Find checklist item and return surrounding context.
+
+    Args:
+        content: Full markdown content
+        item_text: Text of the checklist item to find
+        context_lines: Number of lines before/after to include
+
+    Returns:
+        Context around the item or None if not found
+    """
+    lines = content.split('\n')
+
+    for i, line in enumerate(lines):
+        if item_text in line and re.match(r'^-\s*\[([ x])\]', line.strip()):
+            # Found the item, extract context
+            start = max(0, i - context_lines)
+            end = min(len(lines), i + context_lines + 1)
+
+            context = '\n'.join(lines[start:end])
+            return context
+
+    return None
+
+
+def extract_item_justification(impl_notes_content: str, item_text: str) -> Optional[str]:
+    """
+    Extract justification text following a checklist item.
+
+    Args:
+        impl_notes_content: Implementation Notes section content
+        item_text: The checklist item to find justification for
+
+    Returns:
+        Justification text (lines following item until next item/section) or None
+
+    Example:
+        >>> content = '''
+        ... - [ ] Item 1 - Deferred to STORY-042
+        ...   **User Approved:** YES
+        ...   **Rationale:** Complexity
+        ... - [x] Item 2 - Completed
+        ... '''
+        >>> extract_item_justification(content, "Item 1")
+        'Deferred to STORY-042\\n**User Approved:** YES\\n**Rationale:** Complexity'
+    """
+    lines = impl_notes_content.split('\n')
+
+    for i, line in enumerate(lines):
+        # Find the item
+        if item_text in line and re.match(r'^-\s*\[([ x])\]', line.strip()):
+            # Extract text from this line until next checklist item
+            justification_lines = []
+
+            # Get remainder of current line after checkbox
+            match = re.match(r'^-\s*\[([ x])\]\s*(.+)$', line.strip())
+            if match:
+                remainder = match.group(2).strip()
+                # Remove item text itself, keep justification part
+                if ' - ' in remainder:
+                    parts = remainder.split(' - ', 1)
+                    if len(parts) > 1:
+                        justification_lines.append(parts[1])
+
+            # Get following lines until next item or section
+            for j in range(i + 1, len(lines)):
+                next_line = lines[j].strip()
+
+                # Stop at next checklist item or section header
+                if re.match(r'^-\s*\[([ x])\]', next_line) or re.match(r'^##', next_line):
+                    break
+
+                # Skip empty lines at start
+                if not justification_lines and not next_line:
+                    continue
+
+                justification_lines.append(lines[j])
+
+            if justification_lines:
+                return '\n'.join(justification_lines).strip()
+
+    return None
+
+
+def count_lines_in_section(content: str, section_name: str) -> int:
+    """
+    Count number of lines in a section.
+
+    Args:
+        content: Full markdown content
+        section_name: Name of section
+
+    Returns:
+        Number of lines in section
+    """
+    section = extract_section(content, section_name)
+    if section:
+        return len(section.split('\n'))
+    return 0
+
+
+# Module exports
+__all__ = [
+    'extract_section',
+    'parse_checklist',
+    'extract_all_sections',
+    'find_checklist_item_context',
+    'extract_item_justification',
+    'count_lines_in_section'
+]

package/src/claude/scripts/devforgeai_cli/utils/story_analyzer.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""
+Story Analyzer for DevForgeAI Story Files
+
+High-level analysis functions for story validation.
+Combines markdown and YAML parsing for story-specific operations.
+"""
+
+import re
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from .markdown_parser import (
+    extract_section,
+    parse_checklist,
+    extract_item_justification
+)
+from .yaml_parser import parse_frontmatter, extract_story_id
+
+
+def load_story_file(story_path: str) -> Tuple[Optional[Dict], str]:
+    """
+    Load story file and parse frontmatter + content.
+
+    Args:
+        story_path: Path to story file
+
+    Returns:
+        Tuple of (frontmatter, content)
+
+    Raises:
+        FileNotFoundError if story doesn't exist
+    """
+    path = Path(story_path)
+    if not path.exists():
+        raise FileNotFoundError(f"Story file not found: {story_path}")
+
+    content = path.read_text(encoding='utf-8')
+    frontmatter, body = parse_frontmatter(content)
+
+    return frontmatter, content
+
+
+def extract_dod_items(story_content: str) -> List[Dict]:
+    """
+    Extract all Definition of Done checklist items.
+
+    Args:
+        story_content: Full story file content
+
+    Returns:
+        List of DoD items with text, checked status, line number
+    """
+    dod_section = extract_section(story_content, "Definition of Done")
+
+    if not dod_section:
+        return []
+
+    return parse_checklist(dod_section)
+
+
+def extract_impl_notes_items(story_content: str) -> List[Dict]:
+    """
+    Extract all Implementation Notes checklist items.
+
+    Args:
+        story_content: Full story file content
+
+    Returns:
+        List of Implementation Notes items with text, checked status
+    """
+    impl_section = extract_section(story_content, "Implementation Notes")
+
+    if not impl_section:
+        return []
+
+    # Implementation Notes can have subsections, extract from full section
+    return parse_checklist(impl_section)
+
+
+def find_dod_impl_mismatch(story_content: str) -> List[Dict]:
+    """
+    Find mismatches between DoD and Implementation Notes status.
+
+    Args:
+        story_content: Full story file content
+
+    Returns:
+        List of mismatches with item text, dod_checked, impl_checked
+
+    Example mismatch (autonomous deferral):
+        DoD: [x] Item completed
+        Impl: [ ] Item - Deferred to STORY-XXX
+    """
+    dod_items = extract_dod_items(story_content)
+    impl_items = extract_impl_notes_items(story_content)
+
+    # Create lookup for impl items by text (extract base text before " - ")
+    impl_lookup = {}
+    for item in impl_items:
+        # Extract base text (everything before " - " if present)
+        base_text = item['text'].split(' - ')[0].strip()
+        impl_lookup[base_text] = item
+
+    mismatches = []
+
+    for dod_item in dod_items:
+        dod_text = dod_item['text'].strip()
+
+        # Try exact match first
+        impl_item = impl_lookup.get(dod_text)
+
+        # If no exact match, try partial match
+        if not impl_item:
+            for impl_key, impl_val in impl_lookup.items():
+                # Match if either contains the other (handles variations)
+                if (impl_key in dod_text or dod_text in impl_key) and len(impl_key) > 5:
+                    impl_item = impl_val
+                    break
+
+        if not impl_item:
+            # DoD item not found in Implementation Notes
+            mismatches.append({
+                'item': dod_text,
+                'dod_checked': dod_item['checked'],
+                'impl_found': False,
+                'impl_checked': None
+            })
+        elif dod_item['checked'] != impl_item['checked']:
+            # Status mismatch
+            mismatches.append({
+                'item': dod_text,
+                'dod_checked': dod_item['checked'],
+                'impl_found': True,
+                'impl_checked': impl_item['checked']
+            })
+
+    return mismatches
+
+
+def check_user_approval_marker(justification_text: str) -> Tuple[bool, Optional[str]]:
+    """
+    Check if justification contains user approval marker.
+
+    Args:
+        justification_text: Text following deferred item
+
+    Returns:
+        Tuple of (has_approval, marker_type)
+        marker_type: "user_approved", "story_reference", "adr_reference", "external_blocker", None
+
+    Valid approval markers:
+    - "User approved:" or "User Approved:"
+    - STORY-XXX reference
+    - ADR-XXX reference
+    - "Blocked by: ... (external)"
+    """
+    if not justification_text:
+        return False, None
+
+    # Check for explicit user approval
+    if re.search(r'User [Aa]pproved:', justification_text):
+        return True, "user_approved"
+
+    # Check for AskUserQuestion mention
+    if 'AskUserQuestion' in justification_text:
+        return True, "user_approved"
+
+    # Check for story reference
+    if re.search(r'STORY-\d+', justification_text):
+        return True, "story_reference"
+
+    # Check for ADR reference
+    if re.search(r'ADR-\d+', justification_text):
+        return True, "adr_reference"
+
+    # Check for external blocker
+    if 'Blocked by:' in justification_text and '(external)' in justification_text:
+        return True, "external_blocker"
+
+    return False, None
+
+
+def extract_story_references(text: str) -> List[str]:
+    """
+    Extract all STORY-XXX references from text.
+
+    Args:
+        text: Text to search
+
+    Returns:
+        List of story IDs (e.g., ["STORY-042", "STORY-100"])
+    """
+    return re.findall(r'STORY-\d+', text)
+
+
+def extract_adr_references(text: str) -> List[str]:
+    """
+    Extract all ADR-XXX references from text.
+
+    Args:
+        text: Text to search
+
+    Returns:
+        List of ADR IDs (e.g., ["ADR-001", "ADR-023"])
+    """
+    return re.findall(r'ADR-\d+', text)
+
+
+def has_implementation_notes(story_content: str) -> bool:
+    """
+    Check if story has Implementation Notes section.
+
+    Args:
+        story_content: Full story file content
+
+    Returns:
+        True if Implementation Notes section exists
+    """
+    impl_section = extract_section(story_content, "Implementation Notes")
+    return impl_section is not None and len(impl_section.strip()) > 0
+
+
+def count_deferred_items(impl_notes_content: str) -> int:
+    """
+    Count number of deferred items in Implementation Notes.
+
+    Args:
+        impl_notes_content: Implementation Notes section content
+
+    Returns:
+        Number of items marked [ ] (incomplete/deferred)
+    """
+    items = parse_checklist(impl_notes_content)
+    return sum(1 for item in items if not item['checked'])
+
+
+# Module exports
+__all__ = [
+    'load_story_file',
+    'extract_dod_items',
+    'extract_impl_notes_items',
+    'find_dod_impl_mismatch',
+    'check_user_approval_marker',
+    'extract_story_references',
+    'extract_adr_references',
+    'has_implementation_notes',
+    'count_deferred_items'
+]

package/src/claude/scripts/devforgeai_cli/utils/yaml_parser.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""
+YAML Parser for DevForgeAI Story Files
+
+Extracts and validates YAML frontmatter from markdown documents.
+"""
+
+import re
+import yaml
+from typing import Dict, List, Optional, Tuple
+
+
+def parse_frontmatter(content: str) -> Tuple[Optional[Dict], str]:
+    """
+    Extract YAML frontmatter from markdown content.
+
+    Args:
+        content: Full markdown content
+
+    Returns:
+        Tuple of (frontmatter_dict, remaining_content)
+        frontmatter_dict is None if no frontmatter found
+
+    Example:
+        >>> content = '''---
+        ... id: STORY-001
+        ... title: Test
+        ... ---
+        ... # Story content'''
+        >>> fm, body = parse_frontmatter(content)
+        >>> fm['id']
+        'STORY-001'
+    """
+    # Match YAML frontmatter: ---\n{yaml}\n---
+    pattern = r'^---\s*\n(.*?)\n---\s*\n(.*)$'
+    match = re.match(pattern, content, re.DOTALL)
+
+    if not match:
+        return None, content
+
+    try:
+        frontmatter_text = match.group(1)
+        remaining_content = match.group(2)
+
+        frontmatter = yaml.safe_load(frontmatter_text)
+
+        return frontmatter, remaining_content
+
+    except yaml.YAMLError as e:
+        # Invalid YAML
+        raise ValueError(f"Invalid YAML frontmatter: {e}")
+
+
+def validate_story_frontmatter(frontmatter: Dict) -> Tuple[bool, List[str]]:
+    """
+    Validate DevForgeAI story frontmatter has required fields.
+
+    Args:
+        frontmatter: Parsed YAML frontmatter dict
+
+    Returns:
+        Tuple of (is_valid, error_messages)
+
+    Required fields for story:
+    - id: STORY-XXX format
+    - title: Non-empty string
+    - status: Valid workflow state
+    """
+    errors = []
+
+    # Required fields
+    required_fields = ['id', 'title', 'status']
+
+    for field in required_fields:
+        if field not in frontmatter:
+            errors.append(f"Missing required field: {field}")
+        elif not frontmatter[field]:
+            errors.append(f"Field {field} is empty")
+
+    # Validate id format
+    if 'id' in frontmatter:
+        story_id = frontmatter['id']
+        if not re.match(r'^STORY-\d+$', story_id):
+            errors.append(f"Invalid id format: '{story_id}' (expected STORY-NNN)")
+
+    # Validate status
+    if 'status' in frontmatter:
+        valid_statuses = [
+            'Backlog', 'Ready for Dev', 'Architecture', 'In Development',
+            'Dev Complete', 'QA In Progress', 'QA Approved', 'QA Failed',
+            'Releasing', 'Released'
+        ]
+        if frontmatter['status'] not in valid_statuses:
+            errors.append(f"Invalid status: '{frontmatter['status']}'")
+
+    # Validate depends_on format (if present) - STORY-090
+    if 'depends_on' in frontmatter:
+        depends_on = frontmatter['depends_on']
+        if depends_on is not None:
+            if not isinstance(depends_on, list):
+                errors.append(f"depends_on must be array, got: {type(depends_on).__name__}")
+            else:
+                from .depends_on_normalizer import is_valid_story_id
+                for idx, item in enumerate(depends_on):
+                    if not is_valid_story_id(str(item)):
+                        errors.append(f"Invalid depends_on[{idx}]: '{item}'")
+
+    return len(errors) == 0, errors
+
+
+def extract_story_id(content: str) -> Optional[str]:
+    """
+    Extract story ID from frontmatter.
+
+    Args:
+        content: Full markdown content
+
+    Returns:
+        Story ID (e.g., "STORY-001") or None
+    """
+    frontmatter, _ = parse_frontmatter(content)
+
+    if frontmatter and 'id' in frontmatter:
+        return frontmatter['id']
+
+    return None
+
+
+def has_valid_frontmatter(content: str) -> bool:
+    """
+    Check if content has valid YAML frontmatter.
+
+    Args:
+        content: Full markdown content
+
+    Returns:
+        True if valid frontmatter exists
+    """
+    try:
+        frontmatter, _ = parse_frontmatter(content)
+        return frontmatter is not None
+    except ValueError:
+        return False
+
+
+# Module exports
+__all__ = [
+    'parse_frontmatter',
+    'validate_story_frontmatter',
+    'extract_story_id',
+    'has_valid_frontmatter'
+]

package/src/claude/scripts/devforgeai_cli/validators/__init__.py

@@ -0,0 +1,27 @@
+"""Validator modules for DevForgeAI CLI."""
+
+from .ast_grep_validator import (
+    AstGrepValidator,
+    parse_version,
+    detect_headless_mode,
+    VersionInfo,
+    InstallAction
+)
+from .grep_fallback import (
+    GrepFallbackAnalyzer,
+    GrepPattern,
+    Violation,
+    log_fallback_warning
+)
+
+__all__ = [
+    'AstGrepValidator',
+    'parse_version',
+    'detect_headless_mode',
+    'VersionInfo',
+    'InstallAction',
+    'GrepFallbackAnalyzer',
+    'GrepPattern',
+    'Violation',
+    'log_fallback_warning'
+]