specfact-cli 0.24.0__tar.gz → 0.24.1__tar.gz

{specfact_cli-0.24.0 → specfact_cli-0.24.1}/.gitignore

@@ -123,4 +123,5 @@ _site/
 findings.json
 answers.json
 questions.json
-docs/project-plans/
+docs/project-plans/
+harness_contracts.py

{specfact_cli-0.24.0 → specfact_cli-0.24.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.24.0
+Version: 0.24.1
 Summary: Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions.
 Project-URL: Homepage, https://github.com/nold-ai/specfact-cli
 Project-URL: Repository, https://github.com/nold-ai/specfact-cli.git

{specfact_cli-0.24.0 → specfact_cli-0.24.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.24.0"
+version = "0.24.1"
 description = "Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts. Automate legacy code documentation and prevent modernization regressions."
 readme = "README.md"
 requires-python = ">=3.11"

{specfact_cli-0.24.0 → specfact_cli-0.24.1}/src/__init__.py

@@ -3,4 +3,4 @@ SpecFact CLI - Spec→Contract→Sentinel tool for contract-driven development.
 """
 
 # Define the package version (kept in sync with pyproject.toml and setup.py)
-__version__ = "0.24.0"
+__version__ = "0.24.1"

{specfact_cli-0.24.0 → specfact_cli-0.24.1}/src/specfact_cli/__init__.py

@@ -9,6 +9,6 @@ This package provides command-line tools for:
 - Validating reproducibility
 """
 
-__version__ = "0.24.0"
+__version__ = "0.24.1"
 
 __all__ = ["__version__"]

{specfact_cli-0.24.0 → specfact_cli-0.24.1}/src/specfact_cli/commands/validate.py

@@ -6,6 +6,7 @@ This module provides validation commands including sidecar validation.
 
 from __future__ import annotations
 
+import re
 from pathlib import Path
 
 import typer
@@ -21,6 +22,92 @@ from specfact_cli.validators.sidecar.orchestrator import initialize_sidecar_work
 app = typer.Typer(name="validate", help="Validation commands", suggest_commands=False)
 console = get_configured_console()
 
+
+@beartype
+def _format_crosshair_error(stderr: str, stdout: str) -> str:
+    """
+    Format CrossHair error messages into user-friendly text.
+
+    Filters out technical errors (like Rich markup errors) and provides
+    actionable error messages.
+
+    Args:
+        stderr: CrossHair stderr output
+        stdout: CrossHair stdout output
+
+    Returns:
+        User-friendly error message or empty string if no actionable error
+    """
+    combined = (stderr + "\n" + stdout).strip()
+    if not combined:
+        return ""
+
+    # Filter out Rich markup errors - these are internal errors, not user-facing
+    error_lower = combined.lower()
+    if "closing tag" in error_lower and "doesn't match any open tag" in error_lower:
+        # This is a Rich internal error - ignore it completely
+        return ""
+
+    # Detect common error patterns and provide user-friendly messages
+    # Python shared library issue (venv Python can't load libraries)
+    if "error while loading shared libraries" in error_lower or "libpython" in error_lower:
+        return (
+            "Python environment issue detected. CrossHair is using system Python instead. "
+            "This is usually harmless - validation will continue with system Python."
+        )
+
+    # CrossHair not found
+    if "not found" in error_lower and ("crosshair" in error_lower or "command" in error_lower):
+        return "CrossHair is not installed or not in PATH. Install it with: pip install crosshair-tool"
+
+    # Timeout
+    if "timeout" in error_lower or "timed out" in error_lower:
+        return (
+            "CrossHair analysis timed out. This is expected for complex applications with many routes. "
+            "Some routes were analyzed before timeout. Check the summary file for partial results. "
+            "To analyze more routes, increase --crosshair-timeout or --crosshair-per-path-timeout."
+        )
+
+    # Import errors
+    if "importerror" in error_lower or "module not found" in error_lower:
+        module_match = re.search(r"no module named ['\"]([^'\"]+)['\"]", error_lower)
+        if module_match:
+            module_name = module_match.group(1)
+            return (
+                f"Missing Python module: {module_name}. "
+                "Ensure all dependencies are installed in the sidecar environment."
+            )
+        return "Missing Python module. Ensure all dependencies are installed."
+
+    # Syntax errors in harness
+    if "syntaxerror" in error_lower or "syntax error" in error_lower:
+        return (
+            "Syntax error in generated harness. This may indicate an issue with contract generation. "
+            "Check the harness file for errors."
+        )
+
+    # Generic error - show a sanitized version (remove paths, technical details)
+    # Only show first line and remove technical details
+    lines = combined.split("\n")
+    first_line = lines[0].strip() if lines else ""
+
+    # Remove common technical noise
+    first_line = re.sub(r"Error: closing tag.*", "", first_line, flags=re.IGNORECASE)
+    first_line = re.sub(r"at position \d+", "", first_line, flags=re.IGNORECASE)
+    first_line = re.sub(r"\.specfact/venv/bin/python.*", "", first_line)
+    first_line = re.sub(r"error while loading shared libraries.*", "", first_line, flags=re.IGNORECASE)
+
+    # If we have a clean message, show it (limited length)
+    if first_line and len(first_line) > 10:
+        # Limit to reasonable length
+        if len(first_line) > 150:
+            first_line = first_line[:147] + "..."
+        return first_line
+
+    # Fallback: generic message
+    return "CrossHair execution failed. Check logs for details."
+
+
 # Create sidecar subcommand group
 sidecar_app = typer.Typer(name="sidecar", help="Sidecar validation commands", suggest_commands=False)
 app.add_typer(sidecar_app)
@@ -136,15 +223,43 @@ def run(
             status = "[green]✓[/green]" if success else "[red]✗[/red]"
             console.print(f"  {status} {key}")
 
+            # Display user-friendly error messages if CrossHair failed
+            if not success:
+                stderr = value.get("stderr", "")
+                stdout = value.get("stdout", "")
+                error_message = _format_crosshair_error(stderr, stdout)
+                if error_message:
+                    # Use markup=False to prevent Rich from parsing brackets in error messages
+                    # This prevents Rich markup errors when error messages contain brackets
+                    try:
+                        console.print("    [red]Error:[/red]", end=" ")
+                        console.print(error_message, markup=False)
+                    except Exception:
+                        # If Rich itself fails (shouldn't happen with markup=False, but be safe)
+                        # Fall back to plain print
+                        print(f"    Error: {error_message}")
+
         # Display summary if available
         if results.get("crosshair_summary"):
             summary = results["crosshair_summary"]
             summary_line = format_summary_line(summary)
-            console.print(f"  {summary_line}")
+            # Use try/except to catch Rich parsing errors
+            try:
+                console.print(f"  {summary_line}")
+            except Exception:
+                # Fall back to plain print if Rich fails
+                print(f"  {summary_line}")
 
             # Show summary file location if generated
             if results.get("crosshair_summary_file"):
-                console.print(f"  Summary file: {results['crosshair_summary_file']}")
+                summary_file_path = results["crosshair_summary_file"]
+                # Use markup=False for paths to prevent Rich from parsing brackets
+                try:
+                    console.print("  Summary file: ", end="")
+                    console.print(str(summary_file_path), markup=False)
+                except Exception:
+                    # Fall back to plain print if Rich fails
+                    print(f"  Summary file: {summary_file_path}")
 
     if results.get("specmatic_skipped"):
         console.print(

{specfact_cli-0.24.0 → specfact_cli-0.24.1}/src/specfact_cli/validators/sidecar/contract_populator.py

@@ -37,6 +37,7 @@ def populate_contracts(contracts_dir: Path, routes: list[RouteInfo], schemas: di
         return 0
 
     populated_count = 0
+    total_paths = 0
 
     for contract_file in contract_files:
         try:
@@ -44,11 +45,16 @@ def populate_contracts(contracts_dir: Path, routes: list[RouteInfo], schemas: di
             if populate_contract(contract_data, routes, schemas):
                 save_contract(contract_file, contract_data)
                 populated_count += 1
+            paths_after = len(contract_data.get("paths", {}))
+            # Count total paths in contract (whether newly added or already existed)
+            total_paths = max(total_paths, paths_after)
         except Exception:
             # Skip contracts that can't be processed
             continue
 
-    return populated_count
+    # Return total number of paths in contracts (gives better indication of what was populated)
+    # If no paths found, return number of contracts modified as fallback
+    return total_paths if total_paths > 0 else populated_count
 
 
 @beartype
@@ -108,38 +114,38 @@ def populate_contract(
 
     for route in routes:
         route_id = f"{route.method}:{route.path}"
-        if route_id in schemas:
-            # Add route to paths if not already present
-            if route.path not in contract_data["paths"]:
-                contract_data["paths"][route.path] = {}
-
-            method_lower = route.method.lower()
-            if method_lower not in contract_data["paths"][route.path]:
-                operation = {
-                    "operationId": route.operation_id,
-                    "summary": f"{route.method} {route.path}",
-                    "responses": {
-                        "200": {"description": "Success"},
-                        "400": {"description": "Bad request"},
-                        "500": {"description": "Internal server error"},
-                    },
-                }
-
-                if route.path_params:
-                    operation["parameters"] = route.path_params
-
-                if route.method.upper() in ("POST", "PUT", "PATCH"):
-                    schema = schemas.get(route_id, {})
-                    if schema:
-                        operation["requestBody"] = {
-                            "content": {
-                                "application/json": {
-                                    "schema": schema,
-                                }
+        # Add route to paths if not already present
+        if route.path not in contract_data["paths"]:
+            contract_data["paths"][route.path] = {}
+
+        method_lower = route.method.lower()
+        if method_lower not in contract_data["paths"][route.path]:
+            operation = {
+                "operationId": route.operation_id,
+                "summary": f"{route.method} {route.path}",
+                "responses": {
+                    "200": {"description": "Success"},
+                    "400": {"description": "Bad request"},
+                    "500": {"description": "Internal server error"},
+                },
+            }
+
+            if route.path_params:
+                operation["parameters"] = route.path_params
+
+            # Add requestBody only if schema is available for POST/PUT/PATCH methods
+            if route.method.upper() in ("POST", "PUT", "PATCH"):
+                schema = schemas.get(route_id, {})
+                if schema:
+                    operation["requestBody"] = {
+                        "content": {
+                            "application/json": {
+                                "schema": schema,
                             }
                         }
+                    }
 
-                contract_data["paths"][route.path][method_lower] = operation
-                modified = True
+            contract_data["paths"][route.path][method_lower] = operation
+            modified = True
 
     return modified

{specfact_cli-0.24.0 → specfact_cli-0.24.1}/src/specfact_cli/validators/sidecar/crosshair_runner.py

@@ -30,6 +30,7 @@ def run_crosshair(
     inputs_path: Path | None = None,
     per_path_timeout: int | None = None,
     per_condition_timeout: int | None = None,
+    python_cmd: str | None = None,
 ) -> dict[str, Any]:
     """
     Run CrossHair on source code or harness.
@@ -40,6 +41,10 @@ def run_crosshair(
         pythonpath: PYTHONPATH for execution
         verbose: Enable verbose output
         repo_path: Optional repository path for environment manager detection
+        inputs_path: Optional path to deterministic inputs JSON file
+        per_path_timeout: Optional timeout per execution path
+        per_condition_timeout: Optional timeout per condition
+        python_cmd: Optional Python command to use (e.g., venv Python path)
 
     Returns:
         Dictionary with execution results
@@ -49,14 +54,20 @@ def run_crosshair(
     if pythonpath:
         env["PYTHONPATH"] = pythonpath
 
-    # Build command using environment manager detection if repo_path provided
-    base_cmd = ["crosshair", "check", str(source_path)]
+    # Build command using venv Python if available, otherwise use system CrossHair
+    python_cmd_path = Path(python_cmd) if python_cmd else None
+    if python_cmd_path and python_cmd_path.exists():
+        # Use venv Python to run CrossHair module
+        base_cmd = [str(python_cmd_path), "-m", "crosshair", "check", str(source_path)]
+    else:
+        # Fall back to system CrossHair
+        base_cmd = ["crosshair", "check", str(source_path)]
     if verbose:
         base_cmd.append("--verbose")
     if per_path_timeout:
-        base_cmd.extend(["--per-path-timeout", str(per_path_timeout)])
+        base_cmd.extend(["--per_path_timeout", str(per_path_timeout)])
     if per_condition_timeout:
-        base_cmd.extend(["--per-condition-timeout", str(per_condition_timeout)])
+        base_cmd.extend(["--per_condition_timeout", str(per_condition_timeout)])
     # Note: CrossHair doesn't directly support inputs.json, but deterministic inputs
     # can be embedded in the harness file itself
 

specfact_cli-0.24.1/src/specfact_cli/validators/sidecar/crosshair_summary.py

@@ -0,0 +1,268 @@
+"""
+CrossHair summary parser for sidecar validation.
+
+This module parses CrossHair output to extract summary statistics
+(confirmed, not confirmed, violations counts).
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from beartype import beartype
+from icontract import ensure
+
+
+@beartype
+@ensure(lambda result: isinstance(result, dict), "Must return dict")
+@ensure(lambda result: "confirmed" in result, "Must include confirmed count")
+@ensure(lambda result: "not_confirmed" in result, "Must include not_confirmed count")
+@ensure(lambda result: "violations" in result, "Must include violations count")
+def parse_crosshair_output(stdout: str, stderr: str) -> dict[str, Any]:
+    """
+    Parse CrossHair output to extract summary statistics and detailed violations.
+
+    CrossHair output format:
+    - By default, only reports "Rejected" (violations)
+    - With --report_all, reports "Confirmed", "Rejected", and "Unknown"
+    - Output format: "FunctionName: <status>" or "FunctionName: <status> <details>"
+    - Counterexamples: "FunctionName: Rejected (counterexample: x=5, result=-5)"
+
+    Args:
+        stdout: CrossHair stdout output
+        stderr: CrossHair stderr output
+
+    Returns:
+        Dictionary with summary statistics and detailed violations:
+        - confirmed: int - Number of confirmed contracts
+        - not_confirmed: int - Number of not confirmed (unknown) contracts
+        - violations: int - Number of violations (rejected) contracts
+        - total: int - Total number of contracts analyzed
+        - violation_details: list[dict] - Detailed violation information with counterexamples
+    """
+    confirmed = 0
+    not_confirmed = 0
+    violations = 0
+    violation_details: list[dict[str, Any]] = []
+
+    # Combine stdout and stderr for parsing
+    combined_output = stdout + "\n" + stderr
+
+    # Pattern for CrossHair output lines
+    # Examples:
+    # "function_name: Confirmed" or "function_name: Confirmed over all paths"
+    # "function_name: Rejected (counterexample: ...)"
+    # "function_name: Unknown" or "function_name: Not confirmed"
+    # "function_name: <status>"
+    confirmed_pattern = re.compile(r":\s*Confirmed", re.IGNORECASE)
+    rejected_pattern = re.compile(r":\s*Rejected\b", re.IGNORECASE)
+    unknown_pattern = re.compile(r":\s*(Unknown|Not confirmed)", re.IGNORECASE)
+
+    # Pattern for extracting function name and counterexample
+    # Format: "function_name: Rejected (counterexample: x=5, result=-5)"
+    counterexample_pattern = re.compile(
+        r"^([^:]+):\s*Rejected\s*\(counterexample:\s*(.+?)\)", re.IGNORECASE | re.MULTILINE
+    )
+
+    # Pattern for extracting function name from status lines
+    function_name_pattern = re.compile(r"^([^:]+):", re.MULTILINE)
+
+    # Extract counterexamples first
+    counterexamples = counterexample_pattern.findall(combined_output)
+    for func_name, counterexample_str in counterexamples:
+        # Parse counterexample string (e.g., "x=5, result=-5")
+        counterexample_dict: dict[str, Any] = {}
+        for part in counterexample_str.split(","):
+            part = part.strip()
+            if "=" in part:
+                key, value = part.split("=", 1)
+                key = key.strip()
+                value = value.strip()
+                # Try to parse value as appropriate type
+                try:
+                    if value.startswith('"') and value.endswith('"'):
+                        counterexample_dict[key] = value[1:-1]  # String
+                    elif value.lower() in ("true", "false"):
+                        counterexample_dict[key] = value.lower() == "true"
+                    elif "." in value:
+                        counterexample_dict[key] = float(value)
+                    else:
+                        counterexample_dict[key] = int(value)
+                except (ValueError, AttributeError):
+                    counterexample_dict[key] = value  # Keep as string if parsing fails
+
+        violation_details.append(
+            {
+                "function": func_name.strip(),
+                "counterexample": counterexample_dict,
+                "raw": f"{func_name}: Rejected (counterexample: {counterexample_str})",
+            }
+        )
+
+    # Count by status
+    lines = combined_output.split("\n")
+    for line in lines:
+        if confirmed_pattern.search(line):
+            confirmed += 1
+        elif rejected_pattern.search(line):
+            violations += 1
+            # If we haven't captured this violation yet, try to extract function name
+            if not any(v["function"] in line for v in violation_details):
+                match = function_name_pattern.match(line)
+                if match:
+                    func_name = match.group(1).strip()
+                    # Filter out paths - only keep valid function names
+                    # Skip if it looks like a path (contains / or starts with /)
+                    if "/" not in func_name and not func_name.startswith("/"):
+                        violation_details.append(
+                            {
+                                "function": func_name,
+                                "counterexample": {},
+                                "raw": line.strip(),
+                            }
+                        )
+        elif unknown_pattern.search(line):
+            not_confirmed += 1
+
+    # If no explicit status found but there's output, check for error patterns
+    # CrossHair may report violations in different formats
+    if confirmed == 0 and not_confirmed == 0 and violations == 0:
+        # Check for error/violation indicators
+        if any(
+            keyword in combined_output.lower()
+            for keyword in ["error", "violation", "counterexample", "failed", "rejected"]
+        ):
+            # Likely violations but not in standard format
+            violations = 1
+            # Try to extract function name from error
+            match = function_name_pattern.search(combined_output)
+            if match:
+                func_name = match.group(1).strip()
+                # Filter out paths - only keep valid function names
+                # Skip if it looks like a path (contains / or starts with /)
+                if "/" not in func_name and not func_name.startswith("/"):
+                    violation_details.append(
+                        {
+                            "function": func_name,
+                            "counterexample": {},
+                            "raw": combined_output.strip()[:200],  # First 200 chars
+                        }
+                    )
+        elif combined_output.strip() and "not found" not in combined_output.lower():
+            # Has output but no clear status - likely unknown/not confirmed
+            not_confirmed = 1
+
+    total = confirmed + not_confirmed + violations
+
+    result: dict[str, Any] = {
+        "confirmed": confirmed,
+        "not_confirmed": not_confirmed,
+        "violations": violations,
+        "total": total,
+    }
+
+    # Add violation details if any were found
+    if violation_details:
+        result["violation_details"] = violation_details
+
+    return result
+
+
+@beartype
+@ensure(lambda result: result.exists() if result else True, "Summary file path must be valid")
+def generate_summary_file(
+    summary: dict[str, Any],
+    reports_dir: Path,
+    timestamp: str | None = None,
+) -> Path:
+    """
+    Generate CrossHair summary JSON file.
+
+    Args:
+        summary: Summary statistics dictionary
+        reports_dir: Directory to save summary file (will be created if it doesn't exist)
+        timestamp: Optional timestamp for filename (defaults to current time)
+
+    Returns:
+        Path to generated summary file
+    """
+    from datetime import datetime
+
+    if timestamp is None:
+        timestamp = datetime.utcnow().strftime("%Y%m%dT%H%M%SZ")
+
+    # Ensure reports directory exists (creates parent directories if needed)
+    reports_dir.mkdir(parents=True, exist_ok=True)
+
+    # Create summary file path
+    summary_file = reports_dir / f"crosshair-summary-{timestamp}.json"
+
+    # Add metadata to summary
+    summary_with_metadata = {
+        "timestamp": timestamp,
+        "summary": summary,
+    }
+
+    # Include violation details if present
+    if "violation_details" in summary:
+        summary_with_metadata["violation_details"] = summary["violation_details"]
+
+    # Write summary file
+    with summary_file.open("w") as f:
+        json.dump(summary_with_metadata, f, indent=2)
+
+    return summary_file
+
+
+@beartype
+@ensure(lambda result: isinstance(result, str), "Must return string")
+def format_summary_line(summary: dict[str, Any]) -> str:
+    """
+    Format summary statistics as a single line for console display.
+
+    Args:
+        summary: Summary statistics dictionary (may include violation_details)
+
+    Returns:
+        Formatted summary line string
+    """
+    confirmed = summary.get("confirmed", 0)
+    not_confirmed = summary.get("not_confirmed", 0)
+    violations = summary.get("violations", 0)
+    total = summary.get("total", 0)
+    violation_details = summary.get("violation_details", [])
+
+    parts = []
+    if confirmed > 0:
+        parts.append(f"{confirmed} confirmed")
+    if not_confirmed > 0:
+        parts.append(f"{not_confirmed} not confirmed")
+    if violations > 0:
+        parts.append(f"{violations} violations")
+        # Add violation details if available
+        if violation_details:
+            # Filter out paths and invalid function names (only keep valid Python identifiers)
+            violation_funcs = []
+            for v in violation_details[:3]:
+                func_name = v.get("function", "unknown")
+                # Skip if it looks like a path (contains / or starts with /)
+                # Only include if it looks like a valid function name (alphanumeric + underscore)
+                if (
+                    "/" not in func_name
+                    and not func_name.startswith("/")
+                    and func_name != "unknown"
+                    and (func_name.replace("_", "").replace(".", "").isalnum() or func_name.startswith("harness_"))
+                ):
+                    violation_funcs.append(func_name)
+
+            if violation_funcs:
+                if len(violation_details) > 3:
+                    violation_funcs.append(f"... ({len(violation_details) - 3} more)")
+                parts.append(f"({', '.join(violation_funcs)})")
+    if total == 0:
+        parts.append("no contracts analyzed")
+
+    return f"CrossHair: {', '.join(parts)}" if parts else "CrossHair: no results"