elspais 0.9.3__py3-none-any.whl → 0.11.1__py3-none-any.whl

elspais/reformat/line_breaks.py

@@ -0,0 +1,220 @@
+# Implements: REQ-int-d00008-C (Line break normalization)
+"""
+Line break normalization for requirement content.
+
+Provides functions to:
+- Remove unnecessary blank lines after section headers
+- Reflow paragraphs (join lines broken mid-sentence)
+- Preserve intentional structure (list items, code blocks)
+
+IMPLEMENTS REQUIREMENTS:
+    REQ-int-d00008-C: Line break normalization SHALL be included.
+"""
+
+import re
+from typing import List, Tuple
+
+
+def normalize_line_breaks(content: str, reflow: bool = True) -> str:
+    """
+    Normalize line breaks in requirement content.
+
+    Args:
+        content: Raw requirement markdown content
+        reflow: If True, also reflow paragraphs (join broken lines)
+
+    Returns:
+        Content with normalized line breaks
+    """
+    lines = content.split('\n')
+    result_lines: List[str] = []
+
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+
+        # Check if this is a section header (## Something)
+        if re.match(r'^##\s+\w', line):
+            result_lines.append(line)
+            # Skip blank lines immediately after section header
+            i += 1
+            while i < len(lines) and lines[i].strip() == '':
+                i += 1
+            # Add single blank line after header for readability
+            result_lines.append('')
+            continue
+
+        # Check if this starts a paragraph that might need reflowing
+        if reflow and line.strip() and not _is_structural_line(line):
+            # Collect paragraph lines
+            para_lines = [line.rstrip()]
+            i += 1
+            while i < len(lines):
+                next_line = lines[i]
+                # Stop at blank lines, structural elements, or next section
+                if (next_line.strip() == '' or
+                    _is_structural_line(next_line) or
+                    re.match(r'^##\s+', next_line)):
+                    break
+                para_lines.append(next_line.rstrip())
+                i += 1
+
+            # Join and reflow the paragraph
+            reflowed = _reflow_paragraph(para_lines)
+            result_lines.append(reflowed)
+            continue
+
+        # Keep structural lines and blank lines as-is
+        result_lines.append(line.rstrip())
+        i += 1
+
+    # Clean up multiple consecutive blank lines
+    return _collapse_blank_lines('\n'.join(result_lines))
+
+
+def _is_structural_line(line: str) -> bool:
+    """
+    Check if a line is structural (should not be reflowed).
+
+    Structural lines include:
+    - List items (A., B., 1., -, *)
+    - Headers (# or ##)
+    - Metadata lines (**Level**: etc)
+    - End markers (*End* ...)
+    - Code fence markers (```)
+    """
+    stripped = line.strip()
+
+    if not stripped:
+        return False
+
+    # Headers
+    if stripped.startswith('#'):
+        return True
+
+    # Lettered assertions (A. B. C. etc)
+    if re.match(r'^[A-Z]\.\s', stripped):
+        return True
+
+    # Numbered lists (1. 2. 3. etc)
+    if re.match(r'^\d+\.\s', stripped):
+        return True
+
+    # Bullet points
+    if stripped.startswith(('- ', '* ', '+ ')):
+        return True
+
+    # Metadata line
+    if stripped.startswith('**Level**:') or stripped.startswith('**Status**:'):
+        return True
+
+    # Combined metadata line
+    if re.match(r'\*\*Level\*\*:', stripped):
+        return True
+
+    # End marker
+    if stripped.startswith('*End*'):
+        return True
+
+    # Code fence
+    if stripped.startswith('```'):
+        return True
+
+    return False
+
+
+def _reflow_paragraph(lines: List[str]) -> str:
+    """
+    Reflow a list of paragraph lines into a single line.
+
+    Args:
+        lines: Lines that form a paragraph
+
+    Returns:
+        Single reflowed line
+    """
+    if not lines:
+        return ''
+
+    if len(lines) == 1:
+        return lines[0]
+
+    # Join lines with space, collapsing multiple spaces
+    joined = ' '.join(line.strip() for line in lines if line.strip())
+    # Collapse multiple spaces
+    return re.sub(r'\s+', ' ', joined)
+
+
+def _collapse_blank_lines(content: str) -> str:
+    """
+    Collapse multiple consecutive blank lines into single blank lines.
+
+    Args:
+        content: Content that may have multiple blank lines
+
+    Returns:
+        Content with at most one blank line between paragraphs
+    """
+    # Replace 3+ newlines with 2 newlines (one blank line)
+    return re.sub(r'\n{3,}', '\n\n', content)
+
+
+def fix_requirement_line_breaks(
+    body: str,
+    rationale: str,
+    reflow: bool = True
+) -> Tuple[str, str]:
+    """
+    Fix line breaks in requirement body and rationale.
+
+    Args:
+        body: Requirement body text
+        rationale: Requirement rationale text
+        reflow: Whether to reflow paragraphs
+
+    Returns:
+        Tuple of (fixed_body, fixed_rationale)
+    """
+    fixed_body = normalize_line_breaks(body, reflow=reflow) if body else ''
+    fixed_rationale = normalize_line_breaks(rationale, reflow=reflow) if rationale else ''
+
+    return fixed_body, fixed_rationale
+
+
+def detect_line_break_issues(content: str) -> List[str]:
+    """
+    Detect potential line break issues in content.
+
+    Returns list of issues found for reporting.
+    """
+    issues = []
+    lines = content.split('\n')
+
+    for i, line in enumerate(lines):
+        # Check for blank line after section header
+        if re.match(r'^##\s+\w', line):
+            # Look ahead for multiple blank lines
+            blank_count = 0
+            j = i + 1
+            while j < len(lines) and lines[j].strip() == '':
+                blank_count += 1
+                j += 1
+            if blank_count > 1:
+                issues.append(
+                    f"Line {i+1}: Multiple blank lines ({blank_count}) after section header"
+                )
+
+        # Check for mid-sentence line break (line ends without punctuation)
+        stripped = line.rstrip()
+        if (stripped and
+            not _is_structural_line(line) and
+            i + 1 < len(lines) and
+            lines[i + 1].strip() and
+            not _is_structural_line(lines[i + 1])):
+            # Line ends with a word (not punctuation), followed by non-empty line
+            if stripped and stripped[-1].isalnum():
+                issues.append(
+                    f"Line {i+1}: Possible mid-sentence line break"
+                )
+
+    return issues

elspais/reformat/prompts.py

@@ -0,0 +1,123 @@
+# Implements: REQ-int-d00008 (Reformat Command)
+"""
+Prompts and JSON schema for Claude Code CLI integration.
+
+Defines the system prompt and output schema for AI-assisted
+requirement reformatting.
+"""
+
+import json
+
+# JSON Schema for structured output validation
+JSON_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "rationale": {
+            "type": "string",
+            "description": "Non-normative context explaining why this requirement exists. No SHALL/MUST language."
+        },
+        "assertions": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "List of assertions, each starting with 'The system SHALL...' or similar prescriptive language."
+        }
+    },
+    "required": ["rationale", "assertions"]
+}
+
+JSON_SCHEMA_STR = json.dumps(JSON_SCHEMA, separators=(',', ':'))
+
+# System prompt for requirement reformatting
+REFORMAT_SYSTEM_PROMPT = """You are a requirements engineering expert specializing in FDA 21 CFR Part 11 compliant clinical trial systems.
+
+Your task is to reformat requirements from an old descriptive format to a new prescriptive assertion-based format.
+
+EXTRACTION RULES:
+1. Extract ALL obligations from the old format (body text, bullet points, acceptance criteria)
+2. Convert each distinct obligation to a labeled assertion
+3. Each assertion MUST use "SHALL" for mandatory obligations or "SHALL NOT" for prohibitions
+4. Each assertion MUST be independently testable (decidable as true/false)
+5. Assertions MUST be prescriptive, not descriptive
+6. Maximum 26 assertions (A-Z) - if more needed, consolidate related obligations
+7. Do NOT add obligations that were not in the original
+8. Do NOT remove or weaken any obligations from the original
+9. Combine related acceptance criteria into single assertions when appropriate
+
+RATIONALE RULES:
+1. The rationale provides context for WHY this requirement exists
+2. Rationale MUST NOT introduce new obligations
+3. Rationale MUST NOT use SHALL/MUST language
+4. Rationale can explain regulatory context, design decisions, or relationships to other requirements
+
+LANGUAGE GUIDELINES:
+- Use "The system SHALL..." for system behaviors
+- Use "The platform SHALL..." for platform-wide requirements
+- Use "Data SHALL..." for data-related requirements
+- Be specific and unambiguous
+- Avoid vague terms like "appropriate", "adequate", "reasonable" unless quantified
+
+OUTPUT FORMAT:
+Return a JSON object with:
+- "rationale": A paragraph explaining the requirement's purpose (no SHALL language)
+- "assertions": An array of strings, each being a complete assertion starting with the subject and SHALL
+
+Example output:
+{
+  "rationale": "This requirement ensures complete audit trails for regulatory compliance. FDA 21 CFR Part 11 mandates that electronic records maintain tamper-evident histories of all modifications.",
+  "assertions": [
+    "The system SHALL store all data changes as immutable events.",
+    "The system SHALL preserve the complete history of all modifications.",
+    "Event records SHALL include timestamp, user ID, and action type.",
+    "The system SHALL NOT allow modification or deletion of stored events."
+  ]
+}"""
+
+
+def build_user_prompt(
+    req_id: str,
+    title: str,
+    level: str,
+    status: str,
+    implements: list,
+    body: str,
+    rationale: str = ""
+) -> str:
+    """
+    Build the user prompt for reformatting a requirement.
+
+    Args:
+        req_id: Requirement ID (e.g., 'REQ-p00046')
+        title: Requirement title
+        level: Requirement level (PRD, Dev, Ops)
+        status: Requirement status (Draft, Active, etc.)
+        implements: List of parent requirement IDs
+        body: Current requirement body text
+        rationale: Current rationale text (if any)
+
+    Returns:
+        User prompt string
+    """
+    implements_str = ", ".join(implements) if implements else "-"
+
+    prompt = f"""Reformat the following requirement from old format to new assertion-based format.
+
+REQUIREMENT ID: {req_id}
+TITLE: {title}
+LEVEL: {level}
+STATUS: {status}
+IMPLEMENTS: {implements_str}
+
+CURRENT BODY:
+{body}
+"""
+
+    if rationale and rationale.strip():
+        prompt += f"""
+CURRENT RATIONALE:
+{rationale}
+"""
+
+    prompt += """
+Extract all obligations and convert them to labeled assertions. Return ONLY the JSON object with "rationale" and "assertions" fields."""
+
+    return prompt

elspais/reformat/transformer.py

@@ -0,0 +1,264 @@
+# Implements: REQ-int-d00008 (Reformat Command)
+"""
+AI-assisted requirement transformation using Claude Code CLI.
+
+Invokes claude CLI to reformat requirements and assembles the output
+into the new format.
+"""
+
+import json
+import subprocess
+import sys
+from typing import List, Optional, Tuple
+
+from elspais.reformat.hierarchy import RequirementNode
+from elspais.reformat.prompts import REFORMAT_SYSTEM_PROMPT, JSON_SCHEMA_STR, build_user_prompt
+
+
+def reformat_requirement(
+    node: RequirementNode,
+    model: str = "sonnet",
+    verbose: bool = False
+) -> Tuple[Optional[dict], bool, str]:
+    """
+    Use Claude CLI to reformat a requirement.
+
+    Args:
+        node: RequirementNode with current content
+        model: Claude model to use (sonnet, opus, haiku)
+        verbose: Print debug information
+
+    Returns:
+        Tuple of (parsed_result, success, error_message)
+        parsed_result is a dict with 'rationale' and 'assertions' keys
+    """
+    # Build the prompt
+    user_prompt = build_user_prompt(
+        req_id=node.req_id,
+        title=node.title,
+        level=node.level,
+        status=node.status,
+        implements=node.implements,
+        body=node.body,
+        rationale=node.rationale
+    )
+
+    # Build the claude command
+    cmd = [
+        'claude',
+        '-p',  # Print mode (non-interactive)
+        '--output-format', 'json',
+        '--json-schema', JSON_SCHEMA_STR,
+        '--system-prompt', REFORMAT_SYSTEM_PROMPT,
+        '--tools', '',  # Disable all tools
+        '--model', model,
+        user_prompt
+    ]
+
+    if verbose:
+        print(f"  Running: claude -p --output-format json ...", file=sys.stderr)
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=120  # 2 minute timeout
+        )
+
+        if result.returncode != 0:
+            error_msg = result.stderr.strip() if result.stderr else "Unknown error"
+            return None, False, f"Claude CLI failed: {error_msg}"
+
+        # Parse the JSON response
+        parsed = parse_claude_response(result.stdout)
+        if parsed is None:
+            return None, False, "Failed to parse Claude response"
+
+        return parsed, True, ""
+
+    except subprocess.TimeoutExpired:
+        return None, False, "Claude CLI timed out"
+    except FileNotFoundError:
+        return None, False, "Claude CLI not found - ensure 'claude' is in PATH"
+    except Exception as e:
+        return None, False, f"Unexpected error: {e}"
+
+
+def parse_claude_response(response: str) -> Optional[dict]:
+    """
+    Parse the JSON response from Claude CLI.
+
+    The response format with --output-format json is a JSON object containing:
+    - type: "result"
+    - subtype: "success" or "error"
+    - structured_output: the actual JSON matching our schema
+    - result: text result (may be empty with structured output)
+
+    Args:
+        response: Raw stdout from claude CLI
+
+    Returns:
+        Parsed dict with 'rationale' and 'assertions', or None on failure
+    """
+    try:
+        data = json.loads(response)
+
+        # Check for error
+        if data.get('is_error') or data.get('subtype') == 'error':
+            return None
+
+        # The structured output is in 'structured_output' field
+        if 'structured_output' in data:
+            structured = data['structured_output']
+            if isinstance(structured, dict) and 'rationale' in structured and 'assertions' in structured:
+                return structured
+
+        # Fallback: Direct result (if schema not used)
+        if 'rationale' in data and 'assertions' in data:
+            return data
+
+        # Fallback: Wrapped in result field
+        if 'result' in data:
+            result = data['result']
+            if isinstance(result, dict) and 'rationale' in result:
+                return result
+            # Result might be a JSON string
+            if isinstance(result, str) and result.strip():
+                try:
+                    parsed = json.loads(result)
+                    if 'rationale' in parsed:
+                        return parsed
+                except json.JSONDecodeError:
+                    pass
+
+        return None
+
+    except json.JSONDecodeError:
+        # Try to extract JSON from the response
+        try:
+            json_start = response.find('{')
+            json_end = response.rfind('}') + 1
+            if json_start >= 0 and json_end > json_start:
+                parsed = json.loads(response[json_start:json_end])
+                if 'structured_output' in parsed:
+                    return parsed['structured_output']
+                if 'rationale' in parsed and 'assertions' in parsed:
+                    return parsed
+        except json.JSONDecodeError:
+            pass
+        return None
+
+
+def assemble_new_format(
+    req_id: str,
+    title: str,
+    level: str,
+    status: str,
+    implements: List[str],
+    rationale: str,
+    assertions: List[str]
+) -> str:
+    """
+    Assemble the new format requirement markdown.
+
+    Args:
+        req_id: Requirement ID (e.g., 'REQ-p00046')
+        title: Requirement title
+        level: Requirement level (PRD, Dev, Ops)
+        status: Requirement status
+        implements: List of parent requirement IDs
+        rationale: Rationale text (from AI)
+        assertions: List of assertion strings (from AI)
+
+    Returns:
+        Complete requirement markdown in new format
+    """
+    # Format implements field
+    if implements:
+        implements_str = ", ".join(implements)
+    else:
+        implements_str = "-"
+
+    # Build header
+    lines = [
+        f"# {req_id}: {title}",
+        "",
+        f"**Level**: {level} | **Status**: {status} | **Implements**: {implements_str}",
+        "",
+    ]
+
+    # Add rationale section
+    lines.append("## Rationale")
+    lines.append("")
+    lines.append(rationale.strip())
+    lines.append("")
+
+    # Add assertions section
+    lines.append("## Assertions")
+    lines.append("")
+
+    # Label assertions A, B, C, etc.
+    for i, assertion in enumerate(assertions):
+        label = chr(ord('A') + i)
+        # Clean up assertion text
+        assertion_text = assertion.strip()
+        # Remove any existing label if present
+        if len(assertion_text) > 2 and assertion_text[1] == '.' and assertion_text[0].isupper():
+            assertion_text = assertion_text[2:].strip()
+        lines.append(f"{label}. {assertion_text}")
+
+    lines.append("")
+
+    # Add footer with placeholder hash (will be updated by elspais)
+    # Use 8 zeros as placeholder - elspais expects valid hex format
+    lines.append(f"*End* *{title}* | **Hash**: 00000000")
+    lines.append("")
+
+    return "\n".join(lines)
+
+
+def validate_reformatted_content(
+    original: RequirementNode,
+    rationale: str,
+    assertions: List[str]
+) -> Tuple[bool, List[str]]:
+    """
+    Validate that reformatted content is well-formed.
+
+    Args:
+        original: Original requirement node
+        rationale: New rationale text
+        assertions: New assertions list
+
+    Returns:
+        Tuple of (is_valid, list of warnings)
+    """
+    warnings = []
+
+    # Check assertions exist
+    if not assertions:
+        warnings.append("No assertions generated")
+        return False, warnings
+
+    # Check each assertion uses SHALL
+    for i, assertion in enumerate(assertions):
+        label = chr(ord('A') + i)
+        if 'SHALL' not in assertion.upper():
+            warnings.append(f"Assertion {label} missing SHALL keyword")
+
+    # Check rationale doesn't use SHALL
+    if 'SHALL' in rationale.upper():
+        warnings.append("Rationale contains SHALL (should be non-normative)")
+
+    # Check assertion count
+    if len(assertions) > 26:
+        warnings.append(f"Too many assertions ({len(assertions)} > 26)")
+        return False, warnings
+
+    # Warning if very few assertions from complex body
+    if len(assertions) < 2 and len(original.body) > 500:
+        warnings.append("Few assertions from large body - may have missed obligations")
+
+    is_valid = not any("missing SHALL" in w or "No assertions" in w for w in warnings)
+    return is_valid, warnings