specfact-cli 0.13.2__tar.gz → 0.13.3__tar.gz

{specfact_cli-0.13.2 → specfact_cli-0.13.3}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.13.2"
+version = "0.13.3"
 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.13.2 → specfact_cli-0.13.3}/resources/prompts/specfact.01-import.md

@@ -33,6 +33,7 @@ Import codebase → plan bundle. CLI extracts routes/schemas/relationships/contr
    - Read `.specfact/projects/<bundle>/enrichment_context.md`
    - Enrich: business context, "why" reasoning, missing acceptance criteria
    - Validate: contracts vs code, feature/story alignment
+   - Save enrichment report to `.specfact/reports/enrichment/` (if created)
 
 3. **Present**: Bundle location, report path, summary (features/stories/contracts/relationships)
 

specfact_cli-0.13.3/resources/prompts/specfact.07-contracts.md

@@ -0,0 +1,310 @@
+---
+description: Analyze contract coverage, generate enhancement prompts, and apply contracts sequentially with careful review.
+---
+
+# SpecFact Contract Enhancement Workflow
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Purpose
+
+Complete contract enhancement workflow: analyze coverage → generate prompts → apply contracts sequentially with careful review.
+
+**When to use:** After codebase analysis, when adding contracts to existing code, improving contract coverage.
+
+**Quick:** `/specfact.07-contracts` (uses active plan) or `/specfact.07-contracts legacy-api`
+
+## Parameters
+
+### Target/Input
+
+- `bundle NAME` (optional argument) - Project bundle name (e.g., legacy-api, auth-module). Default: active plan (set via `plan select`)
+- `--repo PATH` - Repository path. Default: current directory (.)
+- `--apply CONTRACTS` - Contract types to apply: 'all-contracts', 'beartype', 'icontract', 'crosshair', or comma-separated list. Default: 'all-contracts'
+- `--min-priority PRIORITY` - Minimum priority for files to process: 'high', 'medium', 'low'. Default: 'low' (process all files missing contracts)
+
+### Behavior/Options
+
+- `--no-interactive` - Non-interactive mode (for CI/CD). Default: False (interactive mode with careful review)
+- `--auto-apply` - Automatically apply contracts after validation (skips confirmation). Default: False (requires confirmation)
+- `--batch-size INT` - Number of files to process before pausing for review. Default: 1 (one file at a time for careful review)
+
+## Workflow
+
+### Step 1: Analyze Contract Coverage
+
+**First, identify files missing contracts:**
+
+```bash
+specfact analyze contracts --repo <repo-path> --bundle <bundle-name>
+# Uses active plan if bundle not specified
+```
+
+**Parse the output to identify:**
+- Files missing beartype (marked with ✗)
+- Files missing icontract (marked with ✗)
+- Files missing crosshair (marked with ✗ or dim ✗)
+- Files that need attention (prioritized in the table)
+
+**Extract file list:**
+- Focus on files marked with ✗ for beartype or icontract
+- Crosshair is optional (marked with dim ✗), but can be included if user requests
+- Filter out pure data model files (they use Pydantic validation)
+
+**Present summary:**
+- Total files analyzed
+- Files missing contracts (by type)
+- Files recommended for enhancement
+
+### Step 2: Generate Enhancement Prompts
+
+**For each file missing contracts, generate a prompt:**
+
+```bash
+specfact generate contracts-prompt <file-path> --apply <contract-types> --bundle <bundle-name>
+```
+
+**Important:**
+- Generate prompts for ALL files missing contracts (or based on --min-priority)
+- Prompts are saved to `.specfact/projects/<bundle-name>/prompts/enhance-<filename>-<contracts>.md`
+- If no bundle, prompts saved to `.specfact/prompts/`
+- Each prompt file contains instructions for the AI IDE to enhance the file
+
+**Present prompt generation summary:**
+- Number of prompts generated
+- Location of prompt files
+- List of files ready for enhancement
+
+### Step 3: User Review and Selection
+
+**Present files for user selection:**
+
+```text
+Files ready for contract enhancement:
+1. src/auth/login.py (missing: beartype, icontract)
+2. src/api/users.py (missing: beartype, icontract, crosshair)
+3. src/utils/helpers.py (missing: beartype)
+...
+
+Select files to enhance (comma-separated numbers, 'all', or 'skip'):
+```
+
+**Wait for user input:**
+- If user selects specific files, process only those
+- If user selects 'all', process all files sequentially
+- If user selects 'skip', move to next step or exit
+
+**In non-interactive mode:**
+- Process all files automatically (or based on --min-priority)
+- Still process sequentially (one at a time) for careful validation
+
+### Step 4: Apply Contracts Sequentially
+
+**For each selected file, apply contracts one at a time:**
+
+**4.1: Read the prompt file**
+
+```bash
+# Prompt file location: .specfact/projects/<bundle-name>/prompts/enhance-<filename>-<contracts>.md
+# Or: .specfact/prompts/enhance-<filename>-<contracts>.md
+```
+
+**4.2: Enhance the code using AI IDE**
+
+- Read the original file
+- Apply contracts according to the prompt instructions
+- Write enhanced code to temporary file: `enhanced_<filename>.py`
+- **DO NOT modify the original file directly**
+
+**4.3: Validate enhanced code**
+
+```bash
+specfact generate contracts-apply enhanced_<filename>.py --original <original-file-path>
+```
+
+**Validation includes:**
+- File size check
+- Syntax validation
+- AST structure comparison
+- Contract imports verification
+- Code quality checks (ruff, pylint, basedpyright, mypy if available)
+- Test execution (scoped to relevant test files)
+
+**4.4: Handle validation results**
+
+**If validation fails:**
+- Review error messages
+- Fix issues in enhanced code
+- Re-validate (up to 3 attempts)
+- If still failing after 3 attempts, skip this file and continue to next
+
+**If validation succeeds:**
+- Show diff preview (what will change)
+- If `--auto-apply` is False, ask for confirmation:
+  ```text
+  Validation passed. Apply changes to <original-file>? (y/n):
+  ```
+- If confirmed (or `--auto-apply` is True), apply changes automatically
+- If not confirmed, skip this file and continue to next
+
+**4.5: Pause for review (if --batch-size > 1)**
+
+After processing `--batch-size` files, pause and show summary:
+```text
+Processed 3/10 files:
+✓ src/auth/login.py - Contracts applied successfully
+✓ src/api/users.py - Contracts applied successfully
+⏭ src/utils/helpers.py - Skipped (user declined)
+
+Continue with next batch? (y/n):
+```
+
+### Step 5: Final Summary
+
+**After all files processed, show final summary:**
+
+```text
+Contract Enhancement Complete
+
+Summary:
+- Files analyzed: 25
+- Files processed: 18
+- Files enhanced: 15
+- Files skipped: 3
+- Files failed: 0
+
+Enhanced files:
+✓ src/auth/login.py (beartype, icontract)
+✓ src/api/users.py (beartype, icontract, crosshair)
+...
+
+Next steps:
+1. Verify contract coverage: specfact analyze contracts --bundle <bundle-name>
+2. Run full test suite: pytest (or your project's test command)
+3. Review changes: git diff
+4. Commit enhanced code
+```
+
+## CLI Enforcement
+
+**CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details.
+
+**Rules:**
+- Execute CLI commands in sequence (analyze → generate → apply)
+- Never modify `.specfact/` directly
+- Always validate before applying changes
+- Process files sequentially for careful review
+- Use `--no-interactive` only in CI/CD environments
+- Use CLI output as grounding for all operations
+
+## Expected Output
+
+### Step 1: Analysis Results
+
+```text
+Contract Coverage Analysis: legacy-api
+Repository: /path/to/repo
+
+┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━┓
+┃ File                                                          ┃ beartype ┃ icontract ┃ crosshair ┃ Coverage ┃
+┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━┩
+│ src/auth/login.py                                             │    ✗     │     ✗     │     ✗     │       0% │
+│ src/api/users.py                                              │    ✗     │     ✗     │     ✗     │       0% │
+...
+
+Summary:
+  Files analyzed: 25
+  Files with beartype: 7 (28.0%)
+  Files with icontract: 7 (28.0%)
+  Files with crosshair: 2 (8.0%)
+
+Found 18 files missing contracts.
+```
+
+### Step 2: Prompt Generation
+
+```text
+Generating enhancement prompts...
+
+✓ Generated prompt for: src/auth/login.py
+  Location: .specfact/projects/legacy-api/prompts/enhance-login.py-all-contracts.md
+
+✓ Generated prompt for: src/api/users.py
+  Location: .specfact/projects/legacy-api/prompts/enhance-users.py-all-contracts.md
+
+...
+
+✓ Generated 18 prompts successfully
+```
+
+### Step 3: User Selection
+
+```text
+Files ready for contract enhancement:
+1. src/auth/login.py (missing: beartype, icontract, crosshair)
+2. src/api/users.py (missing: beartype, icontract, crosshair)
+3. src/utils/helpers.py (missing: beartype)
+...
+
+Select files to enhance (comma-separated numbers, 'all', or 'skip'): all
+```
+
+### Step 4: Sequential Application
+
+```text
+Processing file 1/18: src/auth/login.py
+
+[Reading prompt file...]
+[Enhancing code with AI IDE...]
+[Writing enhanced code to: enhanced_login.py]
+
+Validating enhanced code...
+✓ File size check: passed
+✓ Syntax validation: passed
+✓ AST structure: passed (15 definitions preserved)
+✓ Contract imports: verified
+✓ Code quality checks: passed (ruff, pylint)
+✓ Tests: 12/12 passed
+
+Diff preview:
++ from beartype import beartype
++ from icontract import require, ensure
+...
+
+Apply changes to src/auth/login.py? (y/n): y
+✓ Contracts applied successfully
+
+[Pausing for review... Press Enter to continue to next file]
+```
+
+## Common Patterns
+
+```bash
+/specfact.07-contracts                    # Uses active plan, all-contracts, interactive
+/specfact.07-contracts legacy-api          # Specific bundle
+/specfact.07-contracts --apply beartype,icontract  # Specific contract types
+/specfact.07-contracts --min-priority high  # Only high-priority files
+/specfact.07-contracts --batch-size 3      # Process 3 files before pausing
+/specfact.07-contracts --auto-apply        # Auto-apply after validation (no confirmation)
+/specfact.07-contracts --no-interactive    # CI/CD mode (still sequential for safety)
+```
+
+## Important Notes
+
+1. **Sequential Processing**: Files are processed one at a time (or in small batches) to allow careful review
+2. **Validation Required**: All enhanced code must pass validation before applying
+3. **User Control**: User can skip files, pause between files, or stop the process
+4. **Data Model Files**: Pure Pydantic/dataclass files are automatically excluded (they use Pydantic validation)
+5. **Prompt Location**: Prompts are saved to bundle-specific directories when bundle is provided
+6. **Temporary Files**: Enhanced code is written to temporary files (`enhanced_<filename>.py`) for validation before applying
+
+## Context
+
+{ARGS}
+

{specfact_cli-0.13.2 → specfact_cli-0.13.3}/resources/prompts/specfact.validate.md

@@ -64,6 +64,11 @@ specfact repro --repo <path> [--verbose] [--fail-fast] [--fix] [--budget <second
 
 **CRITICAL**: Always use SpecFact CLI commands. See [CLI Enforcement Rules](./shared/cli-enforcement.md) for details.
 
+**Rules:**
+- Execute CLI first - never create artifacts directly
+- Never modify `.specfact/` directly
+- Use CLI output as grounding for validation results
+
 ## Expected Output
 
 ### Success

{specfact_cli-0.13.2 → specfact_cli-0.13.3}/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.13.2"
+__version__ = "0.13.3"

{specfact_cli-0.13.2 → specfact_cli-0.13.3}/src/specfact_cli/__init__.py

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

{specfact_cli-0.13.2 → specfact_cli-0.13.3}/src/specfact_cli/commands/analyze.py

@@ -7,6 +7,7 @@ contract coverage, code quality metrics, and enhancement opportunities.
 
 from __future__ import annotations
 
+import ast
 from pathlib import Path
 
 import typer
@@ -207,6 +208,30 @@ def _analyze_file_quality(file_path: Path) -> CodeQuality:
         with file_path.open(encoding="utf-8") as f:
             content = f.read()
 
+        # Quick check: if file is in models/ directory, likely a data model file
+        # This avoids expensive AST parsing for most data model files
+        file_str = str(file_path)
+        is_models_dir = "/models/" in file_str or "\\models\\" in file_str
+
+        # For files in models/ directory, do quick AST check to confirm
+        if is_models_dir:
+            try:
+                import ast
+
+                tree = ast.parse(content, filename=str(file_path))
+                # Quick check: if only BaseModel classes with no business logic, skip contract check
+                if _is_pure_data_model_file(tree):
+                    return CodeQuality(
+                        beartype=True,  # Pydantic provides type validation
+                        icontract=True,  # Pydantic provides validation (Field validators)
+                        crosshair=False,  # CrossHair not typically used for data models
+                        coverage=0.0,
+                    )
+            except (SyntaxError, ValueError):
+                # If AST parsing fails, fall through to normal check
+                pass
+
+        # Check for contract decorators in content
         has_beartype = "beartype" in content or "@beartype" in content
         has_icontract = "icontract" in content or "@require" in content or "@ensure" in content
         has_crosshair = "crosshair" in content.lower()
@@ -223,3 +248,86 @@ def _analyze_file_quality(file_path: Path) -> CodeQuality:
     except Exception:
         # Return default quality if analysis fails
         return CodeQuality()
+
+
+def _is_pure_data_model_file(tree: ast.AST) -> bool:
+    """
+    Quick check if file contains only pure data models (Pydantic BaseModel, dataclasses) with no business logic.
+
+    Returns:
+        True if file is pure data models, False otherwise
+    """
+    has_pydantic_models = False
+    has_dataclasses = False
+    has_business_logic = False
+
+    # Standard methods that don't need contracts (including common helper methods)
+    standard_methods = {
+        "__init__",
+        "__str__",
+        "__repr__",
+        "__eq__",
+        "__hash__",
+        "model_dump",
+        "model_validate",
+        "dict",
+        "json",
+        "copy",
+        "update",
+        # Common helper methods on data models (convenience methods, not business logic)
+        "compute_summary",
+        "update_summary",
+        "to_dict",
+        "from_dict",
+        "validate",
+        "serialize",
+        "deserialize",
+    }
+
+    # Check module-level functions and class methods separately
+    # First, collect all classes and check their methods
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            # Check methods in this class
+            for item in node.body:
+                if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)) and item.name not in standard_methods:
+                    # Non-standard method - likely business logic
+                    has_business_logic = True
+                    break
+            if has_business_logic:
+                break
+
+    # Then check for module-level functions (functions not inside any class)
+    if not has_business_logic and isinstance(tree, ast.Module):
+        # Get all top-level nodes (module body)
+        for node in tree.body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and not node.name.startswith(
+                "_"
+            ):  # Public functions
+                has_business_logic = True
+                break
+
+    # Check for Pydantic models and dataclasses
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef):
+            for base in node.bases:
+                if isinstance(base, ast.Name) and base.id == "BaseModel":
+                    has_pydantic_models = True
+                    break
+                if isinstance(base, ast.Attribute) and base.attr == "BaseModel":
+                    has_pydantic_models = True
+                    break
+
+            for decorator in node.decorator_list:
+                if (isinstance(decorator, ast.Name) and decorator.id == "dataclass") or (
+                    isinstance(decorator, ast.Attribute) and decorator.attr == "dataclass"
+                ):
+                    has_dataclasses = True
+                    break
+
+    # Business logic check is done above (methods and module-level functions)
+
+    # File is pure data model if:
+    # 1. Has Pydantic models or dataclasses
+    # 2. No business logic methods or functions
+    return (has_pydantic_models or has_dataclasses) and not has_business_logic

{specfact_cli-0.13.2 → specfact_cli-0.13.3}/src/specfact_cli/utils/ide_setup.py

@@ -119,6 +119,7 @@ SPECFACT_COMMANDS = [
     "specfact.04-sdd",
     "specfact.05-enforce",
     "specfact.06-sync",
+    "specfact.07-contracts",
     "specfact.compare",
     "specfact.validate",
 ]