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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.23.1
+Version: 0.24.0
 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
@@ -368,6 +368,10 @@ specfact init --ide cursor --install-deps
 ```bash
 # Analyze legacy codebase (most common use case)
 specfact import from-code my-project --repo .
+
+# Or validate external codebase without modifying source (sidecar validation)
+specfact validate sidecar init my-project /path/to/repo
+specfact validate sidecar run my-project /path/to/repo
 ```
 
 **⏱️ Timing:** Analysis typically takes **10-15 minutes** for typical repositories (e.g., `specfact-cli` itself with several hundred features & contracts). Smaller codebases may complete in 2-5 minutes. Large codebases (3000+ features) may take 15-30 minutes, but progress reporting shows real-time status. The analysis performs AST parsing, Semgrep pattern detection, and Specmatic integration.
@@ -432,8 +436,10 @@ specfact import from-code my-project --repo .
 - **Prevent regressions** with runtime contract validation
 - **CI/CD integration** - Block bad code from merging
 - **Works offline** - No cloud required
+- **Sidecar validation** - Validate external codebases without modifying source code
 
-👉 **[Command Reference](docs/reference/commands.md)** - All enforcement commands
+👉 **[Command Reference](docs/reference/commands.md)** - All enforcement commands  
+👉 **[Sidecar Validation Guide](docs/guides/sidecar-validation.md)** - Validate external codebases
 
 ### 👥 Team Collaboration
 
@@ -463,6 +469,12 @@ specfact import from-code my-project --repo .
 
 👉 **[Brownfield Modernization Guide](docs/guides/brownfield-engineer.md)** - Complete walkthrough
 
+### 1.5. Validating External Codebases (Sidecar Validation) 🆕
+
+**Problem:** Need to validate third-party libraries or legacy codebases without modifying source code
+
+👉 **[Sidecar Validation Guide](docs/guides/sidecar-validation.md)** - Validate external codebases with contract testing
+
 ### 2. Working with a Team
 
 **Problem:** Need team collaboration with role-based workflows
@@ -502,6 +514,7 @@ specfact import from-code my-project --repo .
 - **[AI IDE Workflow](docs/guides/ai-ide-workflow.md)** ⭐ **NEW** - AI-assisted development
 - **[Agile/Scrum Workflows](docs/guides/agile-scrum-workflows.md)** ⭐ - Team collaboration
 - **[Integrations Overview](docs/guides/integrations-overview.md)** ⭐ **NEW** - All integrations
+- **[Sidecar Validation](docs/guides/sidecar-validation.md)** 🆕 - Validate external codebases without modifying source
 - **[Use Cases](docs/guides/use-cases.md)** - Common scenarios
 
 ### Integration Guides

{specfact_cli-0.23.1 → specfact_cli-0.24.0}/README.md

@@ -93,6 +93,10 @@ specfact init --ide cursor --install-deps
 ```bash
 # Analyze legacy codebase (most common use case)
 specfact import from-code my-project --repo .
+
+# Or validate external codebase without modifying source (sidecar validation)
+specfact validate sidecar init my-project /path/to/repo
+specfact validate sidecar run my-project /path/to/repo
 ```
 
 **⏱️ Timing:** Analysis typically takes **10-15 minutes** for typical repositories (e.g., `specfact-cli` itself with several hundred features & contracts). Smaller codebases may complete in 2-5 minutes. Large codebases (3000+ features) may take 15-30 minutes, but progress reporting shows real-time status. The analysis performs AST parsing, Semgrep pattern detection, and Specmatic integration.
@@ -157,8 +161,10 @@ specfact import from-code my-project --repo .
 - **Prevent regressions** with runtime contract validation
 - **CI/CD integration** - Block bad code from merging
 - **Works offline** - No cloud required
+- **Sidecar validation** - Validate external codebases without modifying source code
 
-👉 **[Command Reference](docs/reference/commands.md)** - All enforcement commands
+👉 **[Command Reference](docs/reference/commands.md)** - All enforcement commands  
+👉 **[Sidecar Validation Guide](docs/guides/sidecar-validation.md)** - Validate external codebases
 
 ### 👥 Team Collaboration
 
@@ -188,6 +194,12 @@ specfact import from-code my-project --repo .
 
 👉 **[Brownfield Modernization Guide](docs/guides/brownfield-engineer.md)** - Complete walkthrough
 
+### 1.5. Validating External Codebases (Sidecar Validation) 🆕
+
+**Problem:** Need to validate third-party libraries or legacy codebases without modifying source code
+
+👉 **[Sidecar Validation Guide](docs/guides/sidecar-validation.md)** - Validate external codebases with contract testing
+
 ### 2. Working with a Team
 
 **Problem:** Need team collaboration with role-based workflows
@@ -227,6 +239,7 @@ specfact import from-code my-project --repo .
 - **[AI IDE Workflow](docs/guides/ai-ide-workflow.md)** ⭐ **NEW** - AI-assisted development
 - **[Agile/Scrum Workflows](docs/guides/agile-scrum-workflows.md)** ⭐ - Team collaboration
 - **[Integrations Overview](docs/guides/integrations-overview.md)** ⭐ **NEW** - All integrations
+- **[Sidecar Validation](docs/guides/sidecar-validation.md)** 🆕 - Validate external codebases without modifying source
 - **[Use Cases](docs/guides/use-cases.md)** - Common scenarios
 
 ### Integration Guides

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.23.1"
+version = "0.24.0"
 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.23.1 → specfact_cli-0.24.0}/resources/templates/sidecar/common/run_sidecar.sh

@@ -148,6 +148,54 @@ _filter_crosshair_dirs() {
   echo "${filtered[@]}"
 }
 
+# Convert source directory paths to Python module names for CrossHair
+# CrossHair expects module names (e.g., "sqlalchemy") not paths (e.g., "lib/sqlalchemy")
+# This function extracts the module name and ensures PYTHONPATH includes the parent directory
+_path_to_module() {
+  local source_path="$1"
+  local repo_path="${2:-${REPO_PATH}}"
+  
+  # Remove trailing slash
+  source_path="${source_path%/}"
+  
+  # If it's an absolute path, make it relative to repo
+  if [[ "$source_path" == /* ]]; then
+    source_path="${source_path#${repo_path}/}"
+  fi
+  
+  # Handle common patterns: lib/pkg, src/pkg, backend/app, pkg
+  # Extract the module name (last component that's a valid Python package)
+  local module_name=""
+  local parent_dir=""
+  
+  if [[ "$source_path" == *"/"* ]]; then
+    # Path has directory structure (e.g., lib/sqlalchemy, src/mypackage)
+    parent_dir="${source_path%/*}"  # Everything before last /
+    module_name="${source_path##*/}"  # Last component
+    
+    # Check if the module directory has __init__.py (is a package)
+    local full_module_path="${repo_path}/${source_path}"
+    if [[ -f "${full_module_path}/__init__.py" ]]; then
+      # It's a package - return module name and parent dir
+      echo "${module_name}|${repo_path}/${parent_dir}"
+      return 0
+    fi
+    
+    # Check subdirectories for packages (e.g., lib/sqlalchemy where sqlalchemy is the package)
+    for subdir in "${full_module_path}"/*; do
+      if [[ -d "$subdir" ]] && [[ -f "${subdir}/__init__.py" ]]; then
+        # Found a package subdirectory
+        echo "$(basename "$subdir")|${full_module_path}"
+        return 0
+      fi
+    done
+  fi
+  
+  # No directory structure or no package found - use the path as-is
+  # This handles cases like "mypackage" where PYTHONPATH is already set correctly
+  echo "${source_path}|"
+}
+
 run_with_timeout() {
   local timeout_secs="$1"
   shift
@@ -427,36 +475,68 @@ if [[ "${RUN_CROSSHAIR}" == "1" ]] && command -v crosshair >/dev/null 2>&1; then
     if [[ -z "${CROSSHAIR_FILTERED_DIRS}" ]]; then
       echo "[sidecar] warning: all source directories filtered out (contain tests), skipping source code analysis"
     else
-    if [[ "${FRAMEWORK_TYPE}" == "django" ]]; then
-      # Use Django-aware wrapper for source code analysis
-      CROSSHAIR_WRAPPER="${SIDECAR_DIR}/../frameworks/django/crosshair_django_wrapper.py"
-      if [[ -f "${CROSSHAIR_WRAPPER}" ]]; then
-        echo "[sidecar] using Django-aware CrossHair wrapper for source analysis"
-        # Export environment variables for Django initialization
-        CROSSHAIR_ENV=""
-        if [[ -n "${DJANGO_SETTINGS_MODULE:-}" ]]; then
-          CROSSHAIR_ENV="DJANGO_SETTINGS_MODULE=${DJANGO_SETTINGS_MODULE} "
+      # Convert source paths to module names for CrossHair
+      # CrossHair expects module names (e.g., "sqlalchemy") not paths (e.g., "lib/sqlalchemy")
+      CROSSHAIR_MODULES=""
+      CROSSHAIR_EXTRA_PYTHONPATH=""
+      for src_dir in ${CROSSHAIR_FILTERED_DIRS}; do
+        MODULE_INFO=$(_path_to_module "$src_dir" "${REPO_PATH}")
+        MODULE_NAME="${MODULE_INFO%%|*}"
+        MODULE_PARENT="${MODULE_INFO##*|}"
+        
+        if [[ -n "$MODULE_NAME" ]]; then
+          CROSSHAIR_MODULES="${CROSSHAIR_MODULES} ${MODULE_NAME}"
+          if [[ -n "$MODULE_PARENT" ]] && [[ ":${CROSSHAIR_EXTRA_PYTHONPATH}:" != *":${MODULE_PARENT}:"* ]]; then
+            CROSSHAIR_EXTRA_PYTHONPATH="${CROSSHAIR_EXTRA_PYTHONPATH}:${MODULE_PARENT}"
+          fi
         fi
-        if [[ -n "${REPO_PATH:-}" ]]; then
-          CROSSHAIR_ENV="${CROSSHAIR_ENV}REPO_PATH=${REPO_PATH} "
+      done
+      CROSSHAIR_MODULES="${CROSSHAIR_MODULES# }"  # Trim leading space
+      CROSSHAIR_EXTRA_PYTHONPATH="${CROSSHAIR_EXTRA_PYTHONPATH#:}"  # Trim leading colon
+      
+      if [[ -z "${CROSSHAIR_MODULES}" ]]; then
+        echo "[sidecar] warning: could not convert source directories to modules, skipping source code analysis"
+      else
+        echo "[sidecar] analyzing modules: ${CROSSHAIR_MODULES}"
+        if [[ -n "${CROSSHAIR_EXTRA_PYTHONPATH}" ]]; then
+          echo "[sidecar] extra PYTHONPATH: ${CROSSHAIR_EXTRA_PYTHONPATH}"
         fi
-        if [[ -n "${PYTHONPATH:-}" ]]; then
-          CROSSHAIR_ENV="${CROSSHAIR_ENV}PYTHONPATH=${PYTHONPATH} "
+        
+        # Build PYTHONPATH for CrossHair (include extra paths for module resolution)
+        CROSSHAIR_PYTHONPATH="${PYTHONPATH:-}"
+        if [[ -n "${CROSSHAIR_EXTRA_PYTHONPATH}" ]]; then
+          CROSSHAIR_PYTHONPATH="${CROSSHAIR_EXTRA_PYTHONPATH}:${CROSSHAIR_PYTHONPATH}"
+        fi
+        
+        if [[ "${FRAMEWORK_TYPE}" == "django" ]]; then
+          # Use Django-aware wrapper for source code analysis
+          CROSSHAIR_WRAPPER="${SIDECAR_DIR}/../frameworks/django/crosshair_django_wrapper.py"
+          if [[ -f "${CROSSHAIR_WRAPPER}" ]]; then
+            echo "[sidecar] using Django-aware CrossHair wrapper for source analysis"
+            # Export environment variables for Django initialization
+            CROSSHAIR_ENV=""
+            if [[ -n "${DJANGO_SETTINGS_MODULE:-}" ]]; then
+              CROSSHAIR_ENV="DJANGO_SETTINGS_MODULE=${DJANGO_SETTINGS_MODULE} "
+            fi
+            if [[ -n "${REPO_PATH:-}" ]]; then
+              CROSSHAIR_ENV="${CROSSHAIR_ENV}REPO_PATH=${REPO_PATH} "
+            fi
+            CROSSHAIR_ENV="${CROSSHAIR_ENV}PYTHONPATH=${CROSSHAIR_PYTHONPATH} "
+            run_and_log "${TIMEOUT_CROSSHAIR}" \
+              "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-crosshair-source.log" \
+              env ${CROSSHAIR_ENV}"${PYTHON_CMD}" "${CROSSHAIR_WRAPPER}" check "${CROSSHAIR_ARGS[@]}" ${CROSSHAIR_MODULES}
+          else
+            echo "[sidecar] warning: Django wrapper not found, using standard CrossHair (may fail)"
+            run_and_log "${TIMEOUT_CROSSHAIR}" \
+              "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-crosshair-source.log" \
+              env PYTHONPATH="${CROSSHAIR_PYTHONPATH}" "${PYTHON_CMD}" -m crosshair check "${CROSSHAIR_ARGS[@]}" ${CROSSHAIR_MODULES}
+          fi
+        else
+          # Standard CrossHair for non-Django projects
+          run_and_log "${TIMEOUT_CROSSHAIR}" \
+            "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-crosshair-source.log" \
+            env PYTHONPATH="${CROSSHAIR_PYTHONPATH}" "${PYTHON_CMD}" -m crosshair check "${CROSSHAIR_ARGS[@]}" ${CROSSHAIR_MODULES}
         fi
-        run_and_log "${TIMEOUT_CROSSHAIR}" \
-          "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-crosshair-source.log" \
-          env ${CROSSHAIR_ENV}"${PYTHON_CMD}" "${CROSSHAIR_WRAPPER}" check "${CROSSHAIR_ARGS[@]}" ${CROSSHAIR_FILTERED_DIRS}
-      else
-        echo "[sidecar] warning: Django wrapper not found, using standard CrossHair (may fail)"
-        run_and_log "${TIMEOUT_CROSSHAIR}" \
-          "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-crosshair-source.log" \
-          "${PYTHON_CMD}" -m crosshair check "${CROSSHAIR_ARGS[@]}" ${CROSSHAIR_FILTERED_DIRS}
-      fi
-    else
-      # Standard CrossHair for non-Django projects
-      run_and_log "${TIMEOUT_CROSSHAIR}" \
-        "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-crosshair-source.log" \
-        "${PYTHON_CMD}" -m crosshair check "${CROSSHAIR_ARGS[@]}" ${CROSSHAIR_FILTERED_DIRS}
       fi
     fi
   fi
@@ -466,21 +546,30 @@ if [[ "${RUN_CROSSHAIR}" == "1" ]] && command -v crosshair >/dev/null 2>&1; then
   # This is the primary analysis method for frameworks without decorators (Django, etc.)
   if [[ -f "${HARNESS_PATH}" ]]; then
     echo "[sidecar] crosshair (harness - external contracts)..."
+    
+    # Build PYTHONPATH for harness analysis:
+    # 1. Sidecar directory (for harness imports like 'common.adapters')
+    # 2. Original PYTHONPATH (for repo modules)
+    HARNESS_DIR="$(cd "$(dirname "${HARNESS_PATH}")" && pwd)"
+    HARNESS_FILE="$(basename "${HARNESS_PATH}")"
+    HARNESS_MODULE="${HARNESS_FILE%.py}"  # Remove .py extension
+    
+    # Build PYTHONPATH: sidecar dir + original PYTHONPATH
+    HARNESS_PYTHONPATH="${HARNESS_DIR}"
+    if [[ -n "${PYTHONPATH:-}" ]]; then
+      HARNESS_PYTHONPATH="${HARNESS_PYTHONPATH}:${PYTHONPATH}"
+    fi
+    
     # Export environment variables for CrossHair subprocess
-    CROSSHAIR_ENV=""
+    CROSSHAIR_ENV="PYTHONPATH=${HARNESS_PYTHONPATH} "
     if [[ -n "${DJANGO_SETTINGS_MODULE:-}" ]]; then
-      CROSSHAIR_ENV="DJANGO_SETTINGS_MODULE=${DJANGO_SETTINGS_MODULE} "
+      CROSSHAIR_ENV="${CROSSHAIR_ENV}DJANGO_SETTINGS_MODULE=${DJANGO_SETTINGS_MODULE} "
     fi
     if [[ -n "${REPO_PATH:-}" ]]; then
       CROSSHAIR_ENV="${CROSSHAIR_ENV}REPO_PATH=${REPO_PATH} "
     fi
-    if [[ -n "${PYTHONPATH:-}" ]]; then
-      CROSSHAIR_ENV="${CROSSHAIR_ENV}PYTHONPATH=${PYTHONPATH} "
-    fi
+    
     # Change to harness directory to ensure valid module name (avoids hyphenated directory names in module path)
-    HARNESS_DIR="$(dirname "${HARNESS_PATH}")"
-    HARNESS_FILE="$(basename "${HARNESS_PATH}")"
-    HARNESS_MODULE="${HARNESS_FILE%.py}"  # Remove .py extension
     run_and_log "${TIMEOUT_CROSSHAIR}" \
       "${SIDECAR_REPORTS_DIR}/${TIMESTAMP}-crosshair-harness.log" \
       bash -c "cd '${HARNESS_DIR}' && env ${CROSSHAIR_ENV}${PYTHON_CMD} -m crosshair check ${CROSSHAIR_ARGS[*]} ${HARNESS_MODULE}"

{specfact_cli-0.23.1 → specfact_cli-0.24.0}/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.23.1"
+__version__ = "0.24.0"

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

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

{specfact_cli-0.23.1 → specfact_cli-0.24.0}/src/specfact_cli/cli.py

@@ -68,6 +68,7 @@ from specfact_cli.commands import (
     sdd,
     spec,
     sync,
+    validate,
 )
 from specfact_cli.modes import OperationalMode, detect_mode
 from specfact_cli.runtime import get_configured_console
@@ -350,6 +351,7 @@ app.add_typer(drift.app, name="drift", help="Detect drift between code and speci
 
 # 11.6. Analysis
 app.add_typer(analyze.app, name="analyze", help="Analyze codebase for contract coverage and quality")
+app.add_typer(validate.app, name="validate", help="Validation commands including sidecar validation")
 
 
 def cli_main() -> None:

{specfact_cli-0.23.1 → specfact_cli-0.24.0}/src/specfact_cli/commands/__init__.py

@@ -19,6 +19,7 @@ from specfact_cli.commands import (
     sdd,
     spec,
     sync,
+    validate,
 )
 
 
@@ -38,4 +39,5 @@ __all__ = [
     "sdd",
     "spec",
     "sync",
+    "validate",
 ]

{specfact_cli-0.23.1 → specfact_cli-0.24.0}/src/specfact_cli/commands/init.py

@@ -146,6 +146,9 @@ def init(
                 "icontract>=2.7.1",
                 "crosshair-tool>=0.0.97",
                 "pytest>=8.4.2",
+                # Sidecar validation tools
+                # Note: specmatic may need separate installation (Java-based tool)
+                # Users may need to install specmatic separately: https://specmatic.in/documentation/getting_started.html
             ]
             console.print("[dim]Installing packages for contract enhancement:[/dim]")
             for package in required_packages:

{specfact_cli-0.23.1 → specfact_cli-0.24.0}/src/specfact_cli/commands/repro.py

@@ -167,6 +167,16 @@ def main(
         help="Time budget in seconds (must be > 0)",
         hidden=True,  # Hidden by default, shown with --help-advanced
     ),
+    sidecar: bool = typer.Option(
+        False,
+        "--sidecar",
+        help="Run sidecar validation for unannotated code (no-edit path)",
+    ),
+    sidecar_bundle: str | None = typer.Option(
+        None,
+        "--sidecar-bundle",
+        help="Bundle name for sidecar validation (required if --sidecar is used)",
+    ),
 ) -> None:
     """
     Run full validation suite for reproducibility.
@@ -182,6 +192,7 @@ def main(
     - Contract exploration (CrossHair) - optional
     - Property tests (pytest tests/contracts/) - optional, only if directory exists
     - Smoke tests (pytest tests/smoke/) - optional, only if directory exists
+    - Sidecar validation (--sidecar) - optional, for unannotated code validation
 
     Works on external repositories without requiring SpecFact CLI adoption.
 
@@ -189,6 +200,7 @@ def main(
         specfact repro --verbose --budget 120
         specfact repro --repo /path/to/external/repo --verbose
         specfact repro --fix --budget 120
+        specfact repro --sidecar --sidecar-bundle legacy-api --repo /path/to/repo
     """
     # If a subcommand was invoked, don't run the main validation
     if ctx.invoked_subcommand is not None:
@@ -201,6 +213,8 @@ def main(
         raise typer.BadParameter("Budget must be positive")
     if not _is_valid_output_path(out):
         raise typer.BadParameter("Output path must exist if provided")
+    if sidecar and not sidecar_bundle:
+        raise typer.BadParameter("--sidecar-bundle is required when --sidecar is used")
 
     from specfact_cli.utils.yaml_utils import dump_yaml
 
@@ -319,6 +333,37 @@ def main(
         dump_yaml(report.to_dict(), out)
         console.print(f"\n[dim]Report written to: {out}[/dim]")
 
+        # Run sidecar validation if requested (after main checks)
+        if sidecar and sidecar_bundle:
+            from specfact_cli.validators.sidecar.models import SidecarConfig
+            from specfact_cli.validators.sidecar.orchestrator import run_sidecar_validation
+            from specfact_cli.validators.sidecar.unannotated_detector import detect_unannotated_in_repo
+
+            console.print("\n[bold cyan]Running sidecar validation for unannotated code...[/bold cyan]")
+
+            # Detect unannotated code
+            unannotated = detect_unannotated_in_repo(repo)
+            if unannotated:
+                console.print(f"[dim]Found {len(unannotated)} unannotated functions[/dim]")
+                # Store unannotated functions info for harness generation
+                sidecar_config = SidecarConfig.create(sidecar_bundle, repo)
+                # Pass unannotated info to orchestrator (via results dict)
+            else:
+                console.print("[dim]No unannotated functions detected (all functions have contracts)[/dim]")
+                sidecar_config = SidecarConfig.create(sidecar_bundle, repo)
+
+            # Run sidecar validation (harness will be generated for unannotated code)
+            sidecar_results = run_sidecar_validation(sidecar_config, console=console)
+
+            # Display sidecar results
+            if sidecar_results.get("crosshair_summary"):
+                summary = sidecar_results["crosshair_summary"]
+                console.print(
+                    f"[dim]Sidecar CrossHair: {summary.get('confirmed', 0)} confirmed, "
+                    f"{summary.get('not_confirmed', 0)} not confirmed, "
+                    f"{summary.get('violations', 0)} violations[/dim]"
+                )
+
         # Exit with appropriate code
         exit_code = report.get_exit_code()
         if exit_code == 0:

specfact_cli-0.24.0/src/specfact_cli/commands/validate.py

@@ -0,0 +1,158 @@
+"""
+Validate command group for SpecFact CLI.
+
+This module provides validation commands including sidecar validation.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from beartype import beartype
+from icontract import require
+
+from specfact_cli.runtime import get_configured_console
+from specfact_cli.validators.sidecar.crosshair_summary import format_summary_line
+from specfact_cli.validators.sidecar.models import SidecarConfig
+from specfact_cli.validators.sidecar.orchestrator import initialize_sidecar_workspace, run_sidecar_validation
+
+
+app = typer.Typer(name="validate", help="Validation commands", suggest_commands=False)
+console = get_configured_console()
+
+# Create sidecar subcommand group
+sidecar_app = typer.Typer(name="sidecar", help="Sidecar validation commands", suggest_commands=False)
+app.add_typer(sidecar_app)
+
+
+@sidecar_app.command()
+@beartype
+@require(lambda bundle_name: bundle_name and len(bundle_name.strip()) > 0, "Bundle name must be non-empty")
+@require(lambda repo_path: repo_path.exists(), "Repository path must exist")
+def init(
+    bundle_name: str = typer.Argument(..., help="Project bundle name (e.g., 'legacy-api')"),
+    repo_path: Path = typer.Argument(..., help="Path to repository root directory"),
+) -> None:
+    """
+    Initialize sidecar workspace for validation.
+
+    Creates sidecar workspace directory structure and configuration for contract-based
+    validation of external codebases without modifying source code.
+
+    **What it does:**
+    - Detects framework type (Django, FastAPI, DRF, pure-python)
+    - Creates sidecar workspace directory structure
+    - Generates configuration files
+    - Detects Python environment (venv, poetry, uv, pip)
+    - Sets up framework-specific configuration (e.g., DJANGO_SETTINGS_MODULE)
+
+    **Example:**
+    ```bash
+    specfact validate sidecar init legacy-api /path/to/repo
+    ```
+
+    **Next steps:**
+    After initialization, run `specfact validate sidecar run` to execute validation.
+    """
+    config = SidecarConfig.create(bundle_name, repo_path)
+
+    console.print(f"[bold]Initializing sidecar workspace for bundle: {bundle_name}[/bold]")
+
+    if initialize_sidecar_workspace(config):
+        console.print("[green]✓[/green] Sidecar workspace initialized successfully")
+        console.print(f"  Framework detected: {config.framework_type}")
+        if config.django_settings_module:
+            console.print(f"  Django settings: {config.django_settings_module}")
+    else:
+        console.print("[red]✗[/red] Failed to initialize sidecar workspace")
+        raise typer.Exit(1)
+
+
+@sidecar_app.command()
+@beartype
+@require(lambda bundle_name: bundle_name and len(bundle_name.strip()) > 0, "Bundle name must be non-empty")
+@require(lambda repo_path: repo_path.exists(), "Repository path must exist")
+def run(
+    bundle_name: str = typer.Argument(..., help="Project bundle name (e.g., 'legacy-api')"),
+    repo_path: Path = typer.Argument(..., help="Path to repository root directory"),
+    run_crosshair: bool = typer.Option(
+        True, "--run-crosshair/--no-run-crosshair", help="Run CrossHair symbolic execution analysis"
+    ),
+    run_specmatic: bool = typer.Option(
+        True, "--run-specmatic/--no-run-specmatic", help="Run Specmatic contract testing validation"
+    ),
+) -> None:
+    """
+    Run sidecar validation workflow.
+
+    Executes complete sidecar validation workflow including framework detection,
+    route extraction, contract population, harness generation, and validation tools.
+
+    **Workflow steps:**
+    1. **Framework Detection**: Automatically detects Django, FastAPI, DRF, or pure-python
+    2. **Route Extraction**: Extracts routes and schemas from framework-specific patterns
+    3. **Contract Population**: Populates OpenAPI contracts with extracted routes/schemas
+    4. **Harness Generation**: Generates CrossHair harness from populated contracts
+    5. **CrossHair Analysis**: Runs symbolic execution on source code and harness (if enabled)
+    6. **Specmatic Validation**: Runs contract testing against API endpoints (if enabled)
+
+    **Example:**
+    ```bash
+    # Run full validation (CrossHair + Specmatic)
+    specfact validate sidecar run legacy-api /path/to/repo
+
+    # Run only CrossHair analysis
+    specfact validate sidecar run legacy-api /path/to/repo --no-run-specmatic
+
+    # Run only Specmatic validation
+    specfact validate sidecar run legacy-api /path/to/repo --no-run-crosshair
+    ```
+
+    **Output:**
+    - Validation results displayed in console
+    - Reports saved to `.specfact/projects/<bundle>/reports/sidecar/`
+    - Progress indicators for long-running operations
+    """
+    config = SidecarConfig.create(bundle_name, repo_path)
+    config.tools.run_crosshair = run_crosshair
+    config.tools.run_specmatic = run_specmatic
+
+    console.print(f"[bold]Running sidecar validation for bundle: {bundle_name}[/bold]")
+
+    results = run_sidecar_validation(config, console=console)
+
+    # Display results
+    console.print("\n[bold]Validation Results:[/bold]")
+    console.print(f"  Framework: {results.get('framework_detected', 'unknown')}")
+    console.print(f"  Routes extracted: {results.get('routes_extracted', 0)}")
+    console.print(f"  Contracts populated: {results.get('contracts_populated', 0)}")
+    console.print(f"  Harness generated: {results.get('harness_generated', False)}")
+
+    if results.get("crosshair_results"):
+        console.print("\n[bold]CrossHair Results:[/bold]")
+        for key, value in results["crosshair_results"].items():
+            success = value.get("success", False)
+            status = "[green]✓[/green]" if success else "[red]✗[/red]"
+            console.print(f"  {status} {key}")
+
+        # Display summary if available
+        if results.get("crosshair_summary"):
+            summary = results["crosshair_summary"]
+            summary_line = format_summary_line(summary)
+            console.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']}")
+
+    if results.get("specmatic_skipped"):
+        console.print(
+            f"\n[yellow]⚠ Specmatic skipped: {results.get('specmatic_skip_reason', 'Unknown reason')}[/yellow]"
+        )
+    elif results.get("specmatic_results"):
+        console.print("\n[bold]Specmatic Results:[/bold]")
+        for key, value in results["specmatic_results"].items():
+            success = value.get("success", False)
+            status = "[green]✓[/green]" if success else "[red]✗[/red]"
+            console.print(f"  {status} {key}")

specfact_cli-0.24.0/src/specfact_cli/validators/sidecar/__init__.py

@@ -0,0 +1,11 @@
+"""
+Sidecar validation package.
+
+This package provides native CLI integration for sidecar validation workflow,
+enabling contract-based validation of external codebases without modifying source code.
+"""
+
+from __future__ import annotations
+
+
+__all__ = []