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

elspais/commands/edit.py

@@ -18,11 +18,10 @@ from typing import Any, Dict, List, Optional
 
 def run(args: argparse.Namespace) -> int:
     """Run the edit command."""
-    from elspais.config.defaults import DEFAULT_CONFIG
-    from elspais.config.loader import find_config_file, get_spec_directories, load_config
+    from elspais.config import DEFAULT_CONFIG, find_config_file, get_spec_directories, load_config
 
     # Load configuration
-    config_path = args.config if hasattr(args, 'config') else None
+    config_path = args.config if hasattr(args, "config") else None
     if config_path is None:
         config_path = find_config_file(Path.cwd())
     if config_path and config_path.exists():
@@ -31,7 +30,7 @@ def run(args: argparse.Namespace) -> int:
         config = DEFAULT_CONFIG
 
     # Get spec directories
-    spec_dir = args.spec_dir if hasattr(args, 'spec_dir') and args.spec_dir else None
+    spec_dir = args.spec_dir if hasattr(args, "spec_dir") and args.spec_dir else None
     spec_dirs = get_spec_directories(spec_dir, config)
     if not spec_dirs:
         print("Error: No spec directories found", file=sys.stderr)
@@ -40,17 +39,17 @@ def run(args: argparse.Namespace) -> int:
     # Use first spec dir as base
     base_spec_dir = spec_dirs[0]
 
-    dry_run = getattr(args, 'dry_run', False)
+    dry_run = getattr(args, "dry_run", False)
 
-    validate_refs = getattr(args, 'validate_refs', False)
+    validate_refs = getattr(args, "validate_refs", False)
 
     # Handle batch mode
-    if hasattr(args, 'from_json') and args.from_json:
+    if hasattr(args, "from_json") and args.from_json:
         return run_batch_edit(args.from_json, base_spec_dir, dry_run, validate_refs)
 
     # Handle single edit mode
-    if hasattr(args, 'req_id') and args.req_id:
-        return run_single_edit(args, base_spec_dir, dry_run)
+    if hasattr(args, "req_id") and args.req_id:
+        return run_single_edit(args, base_spec_dir, dry_run, validate_refs)
 
     print("Error: Must specify --req-id or --from-json", file=sys.stderr)
     return 1
@@ -95,7 +94,9 @@ def run_batch_edit(
     return 0
 
 
-def run_single_edit(args: argparse.Namespace, spec_dir: Path, dry_run: bool) -> int:
+def run_single_edit(
+    args: argparse.Namespace, spec_dir: Path, dry_run: bool, validate_refs: bool = False
+) -> int:
     """Run single requirement edit."""
     req_id = args.req_id
 
@@ -108,19 +109,38 @@ def run_single_edit(args: argparse.Namespace, spec_dir: Path, dry_run: bool) ->
     file_path = location["file_path"]
     results = []
 
+    # Collect valid refs if validation is enabled
+    valid_refs: Optional[set] = None
+    if validate_refs:
+        valid_refs = collect_all_req_ids(spec_dir)
+
     # Apply implements change
-    if hasattr(args, 'implements') and args.implements is not None:
+    if hasattr(args, "implements") and args.implements is not None:
         impl_list = [i.strip() for i in args.implements.split(",")]
+
+        # Validate references if enabled
+        if validate_refs and valid_refs:
+            invalid_refs = []
+            for ref in impl_list:
+                if ref not in valid_refs and f"REQ-{ref}" not in valid_refs:
+                    invalid_refs.append(ref)
+            if invalid_refs:
+                print(
+                    f"Error: Invalid implements references: {', '.join(invalid_refs)}",
+                    file=sys.stderr,
+                )
+                return 1
+
         result = modify_implements(file_path, req_id, impl_list, dry_run=dry_run)
         results.append(("implements", result))
 
     # Apply status change
-    if hasattr(args, 'status') and args.status:
+    if hasattr(args, "status") and args.status:
         result = modify_status(file_path, req_id, args.status, dry_run=dry_run)
         results.append(("status", result))
 
     # Apply move
-    if hasattr(args, 'move_to') and args.move_to:
+    if hasattr(args, "move_to") and args.move_to:
         dest_path = spec_dir / args.move_to
         result = move_requirement(file_path, dest_path, req_id, dry_run=dry_run)
         results.append(("move", result))
@@ -156,15 +176,15 @@ def find_requirement_in_files(
     Returns:
         Dict with file_path, req_id, line_number, or None if not found
     """
-    # Pattern to match requirement header
-    pattern = re.compile(rf'^#\s*{re.escape(req_id)}:', re.MULTILINE)
+    # Pattern to match requirement header (any markdown header level ##, ###, etc.)
+    pattern = re.compile(rf"^#+\s*{re.escape(req_id)}:", re.MULTILINE)
 
     for md_file in spec_dir.rglob("*.md"):
         content = md_file.read_text()
         match = pattern.search(content)
         if match:
             # Count line number
-            line_number = content[:match.start()].count('\n') + 1
+            line_number = content[: match.start()].count("\n") + 1
             return {
                 "file_path": md_file,
                 "req_id": req_id,
@@ -194,8 +214,8 @@ def modify_implements(
     """
     content = file_path.read_text()
 
-    # Find the requirement header
-    req_pattern = re.compile(rf'^(#\s*{re.escape(req_id)}:[^\n]*\n)', re.MULTILINE)
+    # Find the requirement header (any markdown header level)
+    req_pattern = re.compile(rf"^(#+\s*{re.escape(req_id)}:[^\n]*\n)", re.MULTILINE)
     req_match = req_pattern.search(content)
 
     if not req_match:
@@ -203,9 +223,9 @@ def modify_implements(
 
     # Find the **Implements**: field after the header
     start_pos = req_match.end()
-    search_region = content[start_pos:start_pos + 500]
+    search_region = content[start_pos : start_pos + 500]
 
-    impl_pattern = re.compile(r'(\*\*Implements\*\*:\s*)([^|\n]+)')
+    impl_pattern = re.compile(r"(\*\*Implements\*\*:\s*)([^|\n]+)")
     impl_match = impl_pattern.search(search_region)
 
     if not impl_match:
@@ -271,8 +291,8 @@ def modify_status(
     """
     content = file_path.read_text()
 
-    # Find the requirement header
-    req_pattern = re.compile(rf'^(#\s*{re.escape(req_id)}:[^\n]*\n)', re.MULTILINE)
+    # Find the requirement header (any markdown header level)
+    req_pattern = re.compile(rf"^(#+\s*{re.escape(req_id)}:[^\n]*\n)", re.MULTILINE)
     req_match = req_pattern.search(content)
 
     if not req_match:
@@ -280,9 +300,9 @@ def modify_status(
 
     # Find the **Status**: field after the header
     start_pos = req_match.end()
-    search_region = content[start_pos:start_pos + 500]
+    search_region = content[start_pos : start_pos + 500]
 
-    status_pattern = re.compile(r'(\*\*Status\*\*:\s*)(\w+)')
+    status_pattern = re.compile(r"(\*\*Status\*\*:\s*)(\w+)")
     status_match = status_pattern.search(search_region)
 
     if not status_match:
@@ -340,13 +360,10 @@ def move_requirement(
     source_content = source_file.read_text()
 
     # Find the requirement block
-    # Pattern: # REQ-xxx: title ... *End* *title* | **Hash**: xxx\n---
+    # Pattern: ## REQ-xxx: title ... *End* *title* | **Hash**: xxx\n---
     req_pattern = re.compile(
-        rf'(^#\s*{re.escape(req_id)}:[^\n]*\n'
-        rf'.*?'
-        rf'\*End\*[^\n]*\n'
-        rf'(?:---\n)?)',
-        re.MULTILINE | re.DOTALL
+        rf"(^#+\s*{re.escape(req_id)}:[^\n]*\n" rf".*?" rf"\*End\*[^\n]*\n" rf"(?:---\n)?)",
+        re.MULTILINE | re.DOTALL,
     )
 
     req_match = req_pattern.search(source_content)
@@ -361,9 +378,9 @@ def move_requirement(
         req_block = req_block.rstrip() + "\n---\n"
 
     # Remove from source
-    new_source_content = source_content[:req_match.start()] + source_content[req_match.end():]
+    new_source_content = source_content[: req_match.start()] + source_content[req_match.end() :]
     # Clean up extra blank lines
-    new_source_content = re.sub(r'\n{3,}', '\n\n', new_source_content)
+    new_source_content = re.sub(r"\n{3,}", "\n\n", new_source_content)
 
     # Add to destination
     dest_content = dest_file.read_text() if dest_file.exists() else ""
@@ -400,8 +417,9 @@ def collect_all_req_ids(spec_dir: Path) -> set:
         Set of requirement IDs found (short form, e.g., "p00001")
     """
     import re
+
     req_ids = set()
-    pattern = re.compile(r'^#\s*(REQ-[A-Za-z0-9-]+):', re.MULTILINE)
+    pattern = re.compile(r"^#+\s*(REQ-[A-Za-z0-9-]+):", re.MULTILINE)
 
     for md_file in spec_dir.rglob("*.md"):
         content = md_file.read_text()
@@ -453,11 +471,13 @@ def batch_edit(
         # Find the requirement
         location = find_requirement_in_files(spec_dir, req_id)
         if not location:
-            results.append({
-                "success": False,
-                "req_id": req_id,
-                "error": f"Requirement {req_id} not found",
-            })
+            results.append(
+                {
+                    "success": False,
+                    "req_id": req_id,
+                    "error": f"Requirement {req_id} not found",
+                }
+            )
             continue
 
         file_path = location["file_path"]
@@ -493,9 +513,7 @@ def batch_edit(
 
         # Apply status change
         if "status" in change:
-            status_result = modify_status(
-                file_path, req_id, change["status"], dry_run=dry_run
-            )
+            status_result = modify_status(file_path, req_id, change["status"], dry_run=dry_run)
             if not status_result["success"]:
                 result = status_result
                 result["req_id"] = req_id
@@ -506,9 +524,7 @@ def batch_edit(
         # Apply move (must be last since it changes file location)
         if "move_to" in change:
             dest_path = spec_dir / change["move_to"]
-            move_result = move_requirement(
-                file_path, dest_path, req_id, dry_run=dry_run
-            )
+            move_result = move_requirement(file_path, dest_path, req_id, dry_run=dry_run)
             if not move_result["success"]:
                 result = move_result
                 result["req_id"] = req_id

elspais/commands/example_cmd.py

@@ -0,0 +1,319 @@
+"""
+elspais.commands.example_cmd - Display requirement format examples.
+
+Quick reference command for requirement format discovery.
+"""
+
+import argparse
+from pathlib import Path
+
+# ============================================================================
+# Requirement Format Templates
+# ============================================================================
+
+REQUIREMENT_TEMPLATE = """# REQ-{type}{id}: Requirement Title
+
+**Level**: {level} | **Status**: Draft | **Implements**: {implements}
+
+## Assertions
+
+A. The system SHALL <do something specific>.
+B. The system SHALL <do another thing>.
+
+## Rationale
+
+<optional non-normative explanation>
+
+*End* *Requirement Title* | **Hash**: 00000000
+
+---
+Level codes: p = PRD (Product), o = OPS (Operations), d = DEV (Development)
+Implements: Use "-" for top-level requirements, or REQ-pXXXXX for children
+Hash: Run `elspais hash update` to compute automatically
+"""
+
+REQUIREMENT_TEMPLATE_PRD = REQUIREMENT_TEMPLATE.format(
+    type="p", id="00001", level="PRD", implements="-"
+)
+
+REQUIREMENT_TEMPLATE_OPS = REQUIREMENT_TEMPLATE.format(
+    type="o", id="00001", level="Ops", implements="REQ-p00001"
+)
+
+REQUIREMENT_TEMPLATE_DEV = REQUIREMENT_TEMPLATE.format(
+    type="d", id="00001", level="Dev", implements="REQ-o00001"
+)
+
+JOURNEY_TEMPLATE = """# JNY-{prefix}-01: User Journey Title
+
+**Actor**: End User
+**Goal**: <what the user wants to accomplish>
+
+## Steps
+
+1. User <does something>
+2. System <responds with something>
+3. User <completes action>
+
+## Requirements
+
+- REQ-p00001: <requirement title>
+- REQ-p00002: <requirement title>
+
+*End* *User Journey Title*
+
+---
+Journey prefix: Use meaningful 2-4 char codes (e.g., AUTH, PAY, ONBD)
+Steps: Describe the happy path interaction
+Requirements: Link to PRD requirements this journey validates
+"""
+
+ASSERTION_RULES = """# Assertion Format Rules
+
+## Basic Format
+Each assertion is a labeled statement using SHALL language:
+
+    A. The system SHALL <do something specific>.
+    B. The system SHALL <do another thing>.
+
+## Label Styles (configurable)
+- uppercase: A, B, C ... Z (default, max 26)
+- numeric: 1, 2, 3 ... or 01, 02, 03 ...
+- alphanumeric: 0-9, A-Z (max 36)
+
+## Keywords
+- SHALL: Required functionality (normative)
+- SHOULD: Recommended but not required
+- MAY: Optional functionality
+
+## Placeholders for Removed Assertions
+When an assertion is removed, use a placeholder to maintain sequential labels:
+
+    A. The system SHALL validate user input.
+    B. Removed.
+    C. The system SHALL log all transactions.
+
+Valid placeholder values: "Removed", "obsolete", "deprecated", "N/A", "-", "reserved"
+
+## Test References
+Tests can reference specific assertions:
+
+    # test_auth.py
+    def test_user_validation():
+        \"\"\"Test REQ-d00001-A assertion.\"\"\"
+        ...
+
+## Configuration
+
+```toml
+[patterns.assertions]
+label_style = "uppercase"  # "uppercase", "numeric", "alphanumeric"
+max_count = 26
+
+[rules.format]
+require_assertions = true
+require_shall = true
+labels_sequential = true
+```
+"""
+
+ID_PATTERNS_TEMPLATE = """# Requirement ID Patterns
+
+## Current Configuration
+
+The ID pattern is built from these components:
+  prefix     = {prefix}
+  id_template = {id_template}
+
+## Standard ID Formats
+
+**Core repository:**
+  PRD: {prefix}-p00001
+  OPS: {prefix}-o00001
+  DEV: {prefix}-d00001
+
+**With assertion reference:**
+  {prefix}-d00001-A    (assertion A of DEV requirement)
+
+**Associated repository (if enabled):**
+  TTN-{prefix}-p00001  (prefixed with associated code)
+
+## Type Levels
+
+{types}
+
+## Examples in this project
+
+  {prefix}-p00001: PRD requirement (Product, Level 1)
+  {prefix}-o00001: OPS requirement (Operations, Level 2)
+  {prefix}-d00001: DEV requirement (Development, Level 3)
+
+Run `elspais config show --section patterns` for full pattern configuration.
+"""
+
+DEFAULT_TEMPLATE = """# Requirement Format Quick Reference
+
+Use `elspais example <type>` for detailed templates:
+
+  elspais example requirement   Show full requirement template
+  elspais example journey       Show user journey template
+  elspais example assertion     Show assertion rules and examples
+  elspais example ids           Show ID patterns from your config
+  elspais example --full        Display spec/requirements-spec.md
+
+## Basic Requirement Structure
+
+```markdown
+# REQ-d00001: Title
+
+**Level**: Dev | **Status**: Draft | **Implements**: REQ-o00001
+
+## Assertions
+
+A. The system SHALL <do something>.
+
+## Rationale
+
+<optional explanation>
+
+*End* *Title* | **Hash**: 00000000
+```
+
+## Key Rules
+
+1. **Assertions** - Use SHALL for required behavior
+2. **Implements** - Children reference parents (dev -> ops -> prd)
+3. **Hash** - Auto-computed with `elspais hash update`
+4. **Sequential labels** - A, B, C... don't skip letters
+
+Run `elspais validate` to check format compliance.
+"""
+
+
+def run(args: argparse.Namespace) -> int:
+    """
+    Run the example command.
+
+    Args:
+        args: Parsed command line arguments
+
+    Returns:
+        Exit code (0 for success)
+    """
+    # Handle --full flag first
+    if args.full:
+        return show_full_spec(args)
+
+    # Handle subcommand
+    subcommand = args.example_type
+
+    if subcommand == "requirement":
+        return show_requirement_template(args)
+    elif subcommand == "journey":
+        return show_journey_template(args)
+    elif subcommand == "assertion":
+        return show_assertion_rules(args)
+    elif subcommand == "ids":
+        return show_id_patterns(args)
+    else:
+        # Default: show quick reference
+        print(DEFAULT_TEMPLATE)
+        return 0
+
+
+def show_requirement_template(args: argparse.Namespace) -> int:
+    """Show requirement template."""
+    print("# Requirement Templates\n")
+    print("## PRD (Product Requirement)")
+    print(REQUIREMENT_TEMPLATE_PRD)
+    print("\n## OPS (Operations Requirement)")
+    print(REQUIREMENT_TEMPLATE_OPS)
+    print("\n## DEV (Development Requirement)")
+    print(REQUIREMENT_TEMPLATE_DEV)
+    return 0
+
+
+def show_journey_template(args: argparse.Namespace) -> int:
+    """Show user journey template."""
+    print(JOURNEY_TEMPLATE)
+    return 0
+
+
+def show_assertion_rules(args: argparse.Namespace) -> int:
+    """Show assertion format rules."""
+    print(ASSERTION_RULES)
+    return 0
+
+
+def show_id_patterns(args: argparse.Namespace) -> int:
+    """Show ID patterns from current configuration."""
+    from elspais.config import load_config
+
+    try:
+        config = load_config(args.config if hasattr(args, "config") else None)
+    except Exception:
+        # Use defaults if no config found
+        config = {
+            "patterns": {
+                "prefix": "REQ",
+                "id_template": "{prefix}-{type}{id}",
+                "types": {
+                    "prd": {"id": "p", "name": "Product Requirement", "level": 1},
+                    "ops": {"id": "o", "name": "Operations Requirement", "level": 2},
+                    "dev": {"id": "d", "name": "Development Requirement", "level": 3},
+                },
+            }
+        }
+
+    patterns = config.get("patterns", {})
+    prefix = patterns.get("prefix", "REQ")
+    id_template = patterns.get("id_template", "{prefix}-{type}{id}")
+    types = patterns.get("types", {})
+
+    # Format types section
+    types_text = ""
+    for type_key, type_info in types.items():
+        if isinstance(type_info, dict):
+            type_id = type_info.get("id", type_key[0])
+            type_name = type_info.get("name", type_key.upper())
+            type_level = type_info.get("level", "?")
+            types_text += f"  {type_key.upper()}: {type_id} = Level {type_level} ({type_name})\n"
+
+    output = ID_PATTERNS_TEMPLATE.format(
+        prefix=prefix,
+        id_template=id_template,
+        types=types_text.strip() if types_text else "  (no types configured)",
+    )
+    print(output)
+    return 0
+
+
+def show_full_spec(args: argparse.Namespace) -> int:
+    """Display the full requirements-spec.md if it exists."""
+    from elspais.config import load_config
+
+    try:
+        config = load_config(args.config if hasattr(args, "config") else None)
+    except Exception:
+        config = {"directories": {"spec": "spec"}}
+
+    spec_dir = config.get("directories", {}).get("spec", "spec")
+    spec_path = Path.cwd() / spec_dir / "requirements-spec.md"
+
+    # Also check for requirements-format.md (alternative name)
+    alt_path = Path.cwd() / spec_dir / "requirements-format.md"
+
+    if spec_path.exists():
+        print(spec_path.read_text())
+        return 0
+    elif alt_path.exists():
+        print(alt_path.read_text())
+        return 0
+    else:
+        print("No requirements specification found.")
+        print("Searched:")
+        print(f"  - {spec_path}")
+        print(f"  - {alt_path}")
+        print()
+        print("Use `elspais format requirement` for a template instead.")
+        return 1