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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.23.0
+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.0 → 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.0 → specfact_cli-0.24.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.23.0"
+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.0 → 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.0 → 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.0"
+__version__ = "0.24.0"

{specfact_cli-0.23.0 → 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.0"
+__version__ = "0.24.0"
 
 __all__ = ["__version__"]

{specfact_cli-0.23.0 → specfact_cli-0.24.0}/src/specfact_cli/analyzers/contract_extractor.py

@@ -260,8 +260,15 @@ class ContractExtractor:
             return repr(node.value)
         if isinstance(node, ast.Name):
             return node.id
-        if isinstance(node, ast.NameConstant):  # Python < 3.8
-            return str(node.value)
+        # Python < 3.8 compatibility - suppress deprecation warning
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            # ast.NameConstant is deprecated in Python 3.8+, removed in 3.14
+            # Keep for backward compatibility with older Python versions
+            if hasattr(ast, "NameConstant") and isinstance(node, ast.NameConstant):
+                return str(node.value)
 
         # Use ast.unparse if available
         if hasattr(ast, "unparse"):

{specfact_cli-0.23.0 → 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.0 → 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",
 ]