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

elspais/cli.py

@@ -10,7 +10,7 @@ from pathlib import Path
 from typing import List, Optional
 
 from elspais import __version__
-from elspais.commands import analyze, changed, config_cmd, edit, hash_cmd, index, init, rules_cmd, trace, validate
+from elspais.commands import analyze, changed, config_cmd, edit, hash_cmd, index, init, rules_cmd, trace, validate, reformat_cmd
 
 
 def create_parser() -> argparse.ArgumentParser:
@@ -22,9 +22,16 @@ def create_parser() -> argparse.ArgumentParser:
         epilog="""
 Examples:
   elspais validate              # Validate all requirements
+  elspais validate --fix        # Auto-fix fixable issues
   elspais trace --format html   # Generate HTML traceability matrix
+  elspais trace --view          # Interactive HTML view
   elspais hash update           # Update all requirement hashes
+  elspais changed               # Show uncommitted spec changes
+  elspais analyze hierarchy     # Show requirement hierarchy tree
+  elspais config show           # View current configuration
   elspais init                  # Create .elspais.toml configuration
+
+For detailed command help: elspais <command> --help
         """,
     )
 
@@ -64,6 +71,21 @@ Examples:
     validate_parser = subparsers.add_parser(
         "validate",
         help="Validate requirements format, links, and hashes",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  elspais validate                      # Validate all requirements
+  elspais validate --fix                # Auto-fix hashes and formatting
+  elspais validate --skip-rule hash.*   # Skip all hash rules
+  elspais validate -j                   # Output JSON for tooling
+  elspais validate --mode core          # Exclude associated repo specs
+
+Common rules to skip:
+  hash.missing     Hash footer is missing
+  hash.mismatch    Hash doesn't match content
+  hierarchy.*      All hierarchy rules
+  format.*         All format rules
+""",
     )
     validate_parser.add_argument(
         "--fix",
@@ -79,7 +101,7 @@ Examples:
     validate_parser.add_argument(
         "--skip-rule",
         action="append",
-        help="Skip specific validation rules",
+        help="Skip validation rules (can be repeated, e.g., hash.*, format.*)",
         metavar="RULE",
     )
     validate_parser.add_argument(
@@ -97,6 +119,12 @@ Examples:
         action="store_true",
         help="Skip test scanning",
     )
+    validate_parser.add_argument(
+        "--mode",
+        choices=["core", "combined"],
+        default="combined",
+        help="Scope: core (this repo only), combined (include sponsor repos)",
+    )
 
     # trace command
     trace_parser = subparsers.add_parser(
@@ -107,7 +135,7 @@ Examples:
         "--format",
         choices=["markdown", "html", "csv", "both"],
         default="both",
-        help="Output format (default: both)",
+        help="Output format: markdown, html, csv, or both (markdown + csv)",
     )
     trace_parser.add_argument(
         "--output",
@@ -115,11 +143,54 @@ Examples:
         help="Output file path",
         metavar="PATH",
     )
+    # trace-view enhanced options (requires elspais[trace-view])
+    trace_parser.add_argument(
+        "--view",
+        action="store_true",
+        help="Generate interactive HTML traceability view (requires trace-view extra)",
+    )
+    trace_parser.add_argument(
+        "--embed-content",
+        action="store_true",
+        help="Embed full requirement markdown in HTML for offline viewing",
+    )
+    trace_parser.add_argument(
+        "--edit-mode",
+        action="store_true",
+        help="Enable in-browser editing of implements and status fields",
+    )
+    trace_parser.add_argument(
+        "--review-mode",
+        action="store_true",
+        help="Enable collaborative review with comments and flags",
+    )
+    trace_parser.add_argument(
+        "--server",
+        action="store_true",
+        help="Start review server (requires trace-review extra)",
+    )
+    trace_parser.add_argument(
+        "--port",
+        type=int,
+        default=8080,
+        help="Port for review server (default: 8080)",
+    )
+    trace_parser.add_argument(
+        "--mode",
+        choices=["core", "sponsor", "combined"],
+        default="core",
+        help="Report mode: core, sponsor, or combined (default: core)",
+    )
+    trace_parser.add_argument(
+        "--sponsor",
+        help="Sponsor name for sponsor-specific reports",
+        metavar="NAME",
+    )
 
     # hash command
     hash_parser = subparsers.add_parser(
         "hash",
-        help="Manage requirement hashes",
+        help="Manage requirement hashes (verify, update)",
     )
     hash_subparsers = hash_parser.add_subparsers(dest="hash_action")
 
@@ -146,7 +217,7 @@ Examples:
     # index command
     index_parser = subparsers.add_parser(
         "index",
-        help="Manage INDEX.md file",
+        help="Manage INDEX.md file (validate, regenerate)",
     )
     index_subparsers = index_parser.add_subparsers(dest="index_action")
 
@@ -162,7 +233,7 @@ Examples:
     # analyze command
     analyze_parser = subparsers.add_parser(
         "analyze",
-        help="Analyze requirement hierarchy",
+        help="Analyze requirement hierarchy (hierarchy, orphans, coverage)",
     )
     analyze_subparsers = analyze_parser.add_subparsers(dest="analyze_action")
 
@@ -172,7 +243,7 @@ Examples:
     )
     analyze_subparsers.add_parser(
         "orphans",
-        help="Find orphaned requirements",
+        help="Find requirements with no parent (missing or invalid Implements)",
     )
     analyze_subparsers.add_parser(
         "coverage",
@@ -209,7 +280,7 @@ Examples:
     version_parser.add_argument(
         "check",
         nargs="?",
-        help="Check for updates",
+        help="Check for updates (not yet implemented)",
     )
 
     # init command
@@ -237,6 +308,17 @@ Examples:
     edit_parser = subparsers.add_parser(
         "edit",
         help="Edit requirements in-place (implements, status, move)",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  elspais edit --req-id REQ-d00001 --status Draft
+  elspais edit --req-id REQ-d00001 --implements REQ-p00001,REQ-p00002
+  elspais edit --req-id REQ-d00001 --move-to roadmap/future.md
+  elspais edit --from-json edits.json
+
+JSON batch format:
+  {"edits": [{"req_id": "...", "status": "...", "implements": [...]}]}
+""",
     )
     edit_parser.add_argument(
         "--req-id",
@@ -277,7 +359,7 @@ Examples:
     # config command
     config_parser = subparsers.add_parser(
         "config",
-        help="View and modify configuration",
+        help="View and modify configuration (show, get, set, ...)",
     )
     config_subparsers = config_parser.add_subparsers(dest="config_action")
 
@@ -373,7 +455,7 @@ Examples:
     # rules command
     rules_parser = subparsers.add_parser(
         "rules",
-        help="View and manage content rules",
+        help="View and manage content rules (list, show)",
     )
     rules_subparsers = rules_parser.add_subparsers(dest="rules_action")
 
@@ -393,6 +475,53 @@ Examples:
         help="Content rule file name (e.g., 'AI-AGENT.md')",
     )
 
+    # reformat-with-claude command
+    reformat_parser = subparsers.add_parser(
+        "reformat-with-claude",
+        help="Reformat requirements using AI (Acceptance Criteria -> Assertions)",
+    )
+    reformat_parser.add_argument(
+        "--start-req",
+        help="Starting requirement ID (default: all PRD requirements)",
+        metavar="ID",
+    )
+    reformat_parser.add_argument(
+        "--depth",
+        type=int,
+        help="Maximum traversal depth (default: unlimited)",
+    )
+    reformat_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview changes without applying",
+    )
+    reformat_parser.add_argument(
+        "--backup",
+        action="store_true",
+        help="Create .bak files before editing",
+    )
+    reformat_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Reformat even if already in new format",
+    )
+    reformat_parser.add_argument(
+        "--fix-line-breaks",
+        action="store_true",
+        help="Normalize line breaks (remove extra blank lines)",
+    )
+    reformat_parser.add_argument(
+        "--line-breaks-only",
+        action="store_true",
+        help="Only fix line breaks, skip AI-based reformatting",
+    )
+    reformat_parser.add_argument(
+        "--mode",
+        choices=["combined", "core-only", "local-only"],
+        default="combined",
+        help="Which repos to include in hierarchy (default: combined)",
+    )
+
     # mcp command
     mcp_parser = subparsers.add_parser(
         "mcp",
@@ -489,6 +618,8 @@ def main(argv: Optional[List[str]] = None) -> int:
             return config_cmd.run(args)
         elif args.command == "rules":
             return rules_cmd.run(args)
+        elif args.command == "reformat-with-claude":
+            return reformat_cmd.run(args)
         elif args.command == "mcp":
             return mcp_command(args)
         else:

elspais/commands/hash_cmd.py

@@ -104,8 +104,16 @@ def run_update(args: argparse.Namespace) -> int:
     else:
         print(f"Updating {len(updates)} hashes...")
         for req_id, req, new_hash in updates:
-            update_hash_in_file(req, new_hash)
-            print(f"  ✓ {req_id}")
+            result = update_hash_in_file(req, new_hash)
+            if result['updated']:
+                print(f"  ✓ {req_id}")
+                old_hash = result['old_hash'] or "(none)"
+                print(f"    [INFO] Hash: {old_hash} -> {result['new_hash']}")
+                if result['title_fixed']:
+                    print(f"    [INFO] Title fixed: \"{result['old_title']}\" -> \"{req.title}\"")
+            else:
+                print(f"  ✗ {req_id}")
+                print(f"    [WARN] Could not find End marker to update")
 
     return 0
 
@@ -138,37 +146,75 @@ def load_requirements(args: argparse.Namespace) -> tuple:
     return config, requirements
 
 
-def update_hash_in_file(req: Requirement, new_hash: str) -> None:
+def update_hash_in_file(req: Requirement, new_hash: str) -> dict:
     """Update the hash in the requirement's source file.
 
-    The replacement is scoped to the specific requirement's end marker
-    (identified by title) to avoid accidentally updating other requirements
-    in the same file that might have the same hash value.
+    Finds the End marker by the old hash value, then replaces the entire line
+    with the correct title and new hash. This handles cases where the End
+    marker title doesn't match the header title.
+
+    Args:
+        req: Requirement object with file_path, title, and hash
+        new_hash: New hash value to write
+
+    Returns:
+        Dict with change info:
+          - 'updated': bool - whether file was modified
+          - 'old_hash': str - previous hash (or None)
+          - 'new_hash': str - new hash value
+          - 'title_fixed': bool - whether title was corrected
+          - 'old_title': str - previous title (if different)
     """
+    import re
+
+    result = {
+        'updated': False,
+        'old_hash': req.hash,
+        'new_hash': new_hash,
+        'title_fixed': False,
+        'old_title': None,
+    }
+
     if not req.file_path:
-        return
+        return result
 
     content = req.file_path.read_text(encoding="utf-8")
-
-    import re
+    new_end_line = f"*End* *{req.title}* | **Hash**: {new_hash}"
 
     if req.hash:
-        # Replace existing hash - SCOPED to this requirement's end marker
-        # Match: *End* *Title* | **Hash**: oldhash
-        # Replace hash only for THIS requirement (identified by title)
-        content = re.sub(
-            rf"(\*End\*\s+\*{re.escape(req.title)}\*\s*\|\s*)\*\*Hash\*\*:\s*{re.escape(req.hash)}",
-            rf"\1**Hash**: {new_hash}",
-            content,
-        )
+        # Strategy: Try title first (most specific), then hash if title not found
+        # This handles both: (1) normal case, (2) mismatched title case
+
+        # First try: match by correct title (handles case where titles match)
+        pattern_by_title = rf"^\*End\*\s+\*{re.escape(req.title)}\*\s*\|\s*\*\*Hash\*\*:\s*[a-fA-F0-9]+\s*$"
+        if re.search(pattern_by_title, content, re.MULTILINE):
+            content, count = re.subn(pattern_by_title, new_end_line, content, flags=re.MULTILINE)
+            if count > 0:
+                result['updated'] = True
+        else:
+            # Second try: find by hash value (handles mismatched title)
+            # Pattern: *End* *AnyTitle* | **Hash**: oldhash
+            pattern_by_hash = rf"^\*End\*\s+\*([^*]+)\*\s*\|\s*\*\*Hash\*\*:\s*{re.escape(req.hash)}\s*$"
+            match = re.search(pattern_by_hash, content, re.MULTILINE)
+
+            if match:
+                old_title = match.group(1)
+                if old_title != req.title:
+                    result['title_fixed'] = True
+                    result['old_title'] = old_title
+
+                # Replace entire line (only first match to avoid affecting other reqs)
+                content = re.sub(pattern_by_hash, new_end_line, content, count=1, flags=re.MULTILINE)
+                result['updated'] = True
     else:
-        # Add hash to end marker
+        # Add hash to end marker (no existing hash)
         # Pattern: *End* *Title* (without hash)
-        # Add: | **Hash**: XXXX
-        content = re.sub(
-            rf"(\*End\*\s+\*{re.escape(req.title)}\*)(?!\s*\|\s*\*\*Hash\*\*)",
-            rf"\1 | **Hash**: {new_hash}",
-            content,
-        )
-
-    req.file_path.write_text(content, encoding="utf-8")
+        pattern = rf"^(\*End\*\s+\*{re.escape(req.title)}\*)(?!\s*\|\s*\*\*Hash\*\*)\s*$"
+        content, count = re.subn(pattern, new_end_line, content, flags=re.MULTILINE)
+        if count > 0:
+            result['updated'] = True
+
+    if result['updated']:
+        req.file_path.write_text(content, encoding="utf-8")
+
+    return result