specfact-cli 0.12.1__tar.gz → 0.13.0__tar.gz

{specfact_cli-0.12.1 → specfact_cli-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfact-cli
-Version: 0.12.1
+Version: 0.13.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
@@ -275,20 +275,58 @@ Description-Content-Type: text/markdown
 
 # SpecFact CLI
 
-> **Understand and Modernize Legacy Code with Confidence**  
-> Automatically extract specs from existing Python code, then enforce them as contracts
+> **Stop vibe coding. Start shipping quality code with contracts.**  
+> Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts
 
+[![PyPI version](https://img.shields.io/pypi/v/specfact-cli.svg)](https://pypi.org/project/specfact-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/specfact-cli.svg)](https://pypi.org/project/specfact-cli/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE.md)
-[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
 [![Status](https://img.shields.io/badge/status-beta-orange.svg)](https://github.com/nold-ai/specfact-cli)
 
+<div align="center">
+
+**[🌐 Learn More at noldai.com](https://noldai.com)** • **[📚 Documentation](https://nold-ai.github.io/specfact-cli)** • **[💬 Support](mailto:hello@noldai.com)**
+
+</div>
+
+---
+
+## 🚀 Quick Start in 60 Seconds
+
+### Install in 10 seconds
+
+```bash
+# Zero-install (recommended)
+uvx --from specfact-cli specfact
+
+# Or install with pip
+pip install specfact-cli
+```
+
+### Your first command (< 60 seconds)
+
+```bash
+# Modernizing legacy code? (Recommended)
+specfact import from-code legacy-api --repo .
+
+# Starting a new project?
+specfact plan init legacy-api --interactive
+
+# Using GitHub Spec-Kit or other tools?
+specfact import from-bridge --repo . --adapter speckit --write
+```
+
+That's it! 🎉
+
+> **Need machine-readable artifacts?** Use `specfact --output-format json …` (or the per-command `--output-format` flag) to emit plan bundles and reports as JSON instead of YAML.
+
 ---
 
 ## What is SpecFact CLI?
 
 A brownfield-first CLI that **reverse engineers your legacy code** into documented specs, then prevents regressions with runtime contract enforcement.
 
-**Stop guessing what your legacy code does.** SpecFact automatically extracts specs from existing code, then enforces them as you modernize.
+**Stop vibe coding. Start shipping quality code with contracts.** SpecFact automatically extracts specs from existing code, then enforces them as you modernize—preventing bugs before they reach production.
 
 **Perfect for:** Teams modernizing legacy Python systems, data pipelines, DevOps scripts
 
@@ -347,37 +385,6 @@ SpecFact CLI works with your existing tools—no new platform to learn. See real
 
 ---
 
-## Quick Start
-
-### Install in 10 seconds
-
-```bash
-# Zero-install (just run it)
-uvx specfact-cli@latest
-
-# Or install with pip
-pip install specfact-cli
-```
-
-### Your first command (< 60 seconds)
-
-```bash
-# Modernizing legacy code? (Recommended)
-specfact import from-code legacy-api --repo .
-
-# Starting a new project?
-specfact plan init legacy-api --interactive
-
-# Using GitHub Spec-Kit or other tools?
-specfact import from-bridge --repo . --adapter speckit --write
-```
-
-That's it! 🎉
-
-> Need machine-readable artifacts? Use `specfact --output-format json …` (or the per-command `--output-format` flag) to emit plan bundles and reports as JSON instead of YAML.
-
----
-
 ## See It In Action
 
 We ran SpecFact CLI **on itself** to prove it works with legacy code:
@@ -477,11 +484,16 @@ SpecFact CLI is licensed under the Apache License 2.0, which means:
 - 💬 **Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions)
 - 🐛 **Found a bug?** [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues)
 - 📧 **Need help?** [hello@noldai.com](mailto:hello@noldai.com)
+- 🌐 **Learn more:** [noldai.com](https://noldai.com)
 
 ---
 
-> **Built with ❤️ by [NOLD AI](https://noldai.com)**
+<div align="center">
+
+**Built with ❤️ by [NOLD AI](https://noldai.com)**
 
 Copyright © 2025 Nold AI (Owner: Dominikus Nold)
 
 **Trademarks**: NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). All other trademarks mentioned in this project are the property of their respective owners. See [TRADEMARKS.md](TRADEMARKS.md) for more information.
+
+</div>

{specfact_cli-0.12.1 → specfact_cli-0.13.0}/README.md

@@ -1,19 +1,57 @@
 # SpecFact CLI
 
-> **Understand and Modernize Legacy Code with Confidence**  
-> Automatically extract specs from existing Python code, then enforce them as contracts
+> **Stop vibe coding. Start shipping quality code with contracts.**  
+> Brownfield-first CLI: Reverse engineer legacy Python → specs → enforced contracts
 
+[![PyPI version](https://img.shields.io/pypi/v/specfact-cli.svg)](https://pypi.org/project/specfact-cli/)
+[![Python versions](https://img.shields.io/pypi/pyversions/specfact-cli.svg)](https://pypi.org/project/specfact-cli/)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE.md)
-[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)
 [![Status](https://img.shields.io/badge/status-beta-orange.svg)](https://github.com/nold-ai/specfact-cli)
 
+<div align="center">
+
+**[🌐 Learn More at noldai.com](https://noldai.com)** • **[📚 Documentation](https://nold-ai.github.io/specfact-cli)** • **[💬 Support](mailto:hello@noldai.com)**
+
+</div>
+
+---
+
+## 🚀 Quick Start in 60 Seconds
+
+### Install in 10 seconds
+
+```bash
+# Zero-install (recommended)
+uvx --from specfact-cli specfact
+
+# Or install with pip
+pip install specfact-cli
+```
+
+### Your first command (< 60 seconds)
+
+```bash
+# Modernizing legacy code? (Recommended)
+specfact import from-code legacy-api --repo .
+
+# Starting a new project?
+specfact plan init legacy-api --interactive
+
+# Using GitHub Spec-Kit or other tools?
+specfact import from-bridge --repo . --adapter speckit --write
+```
+
+That's it! 🎉
+
+> **Need machine-readable artifacts?** Use `specfact --output-format json …` (or the per-command `--output-format` flag) to emit plan bundles and reports as JSON instead of YAML.
+
 ---
 
 ## What is SpecFact CLI?
 
 A brownfield-first CLI that **reverse engineers your legacy code** into documented specs, then prevents regressions with runtime contract enforcement.
 
-**Stop guessing what your legacy code does.** SpecFact automatically extracts specs from existing code, then enforces them as you modernize.
+**Stop vibe coding. Start shipping quality code with contracts.** SpecFact automatically extracts specs from existing code, then enforces them as you modernize—preventing bugs before they reach production.
 
 **Perfect for:** Teams modernizing legacy Python systems, data pipelines, DevOps scripts
 
@@ -72,37 +110,6 @@ SpecFact CLI works with your existing tools—no new platform to learn. See real
 
 ---
 
-## Quick Start
-
-### Install in 10 seconds
-
-```bash
-# Zero-install (just run it)
-uvx specfact-cli@latest
-
-# Or install with pip
-pip install specfact-cli
-```
-
-### Your first command (< 60 seconds)
-
-```bash
-# Modernizing legacy code? (Recommended)
-specfact import from-code legacy-api --repo .
-
-# Starting a new project?
-specfact plan init legacy-api --interactive
-
-# Using GitHub Spec-Kit or other tools?
-specfact import from-bridge --repo . --adapter speckit --write
-```
-
-That's it! 🎉
-
-> Need machine-readable artifacts? Use `specfact --output-format json …` (or the per-command `--output-format` flag) to emit plan bundles and reports as JSON instead of YAML.
-
----
-
 ## See It In Action
 
 We ran SpecFact CLI **on itself** to prove it works with legacy code:
@@ -202,11 +209,16 @@ SpecFact CLI is licensed under the Apache License 2.0, which means:
 - 💬 **Questions?** [GitHub Discussions](https://github.com/nold-ai/specfact-cli/discussions)
 - 🐛 **Found a bug?** [GitHub Issues](https://github.com/nold-ai/specfact-cli/issues)
 - 📧 **Need help?** [hello@noldai.com](mailto:hello@noldai.com)
+- 🌐 **Learn more:** [noldai.com](https://noldai.com)
 
 ---
 
-> **Built with ❤️ by [NOLD AI](https://noldai.com)**
+<div align="center">
+
+**Built with ❤️ by [NOLD AI](https://noldai.com)**
 
 Copyright © 2025 Nold AI (Owner: Dominikus Nold)
 
 **Trademarks**: NOLD AI (NOLDAI) is a registered trademark (wordmark) at the European Union Intellectual Property Office (EUIPO). All other trademarks mentioned in this project are the property of their respective owners. See [TRADEMARKS.md](TRADEMARKS.md) for more information.
+
+</div>

{specfact_cli-0.12.1 → specfact_cli-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "specfact-cli"
-version = "0.12.1"
+version = "0.13.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.12.1 → specfact_cli-0.13.0}/src/specfact_cli/__init__.py

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

{specfact_cli-0.12.1 → specfact_cli-0.13.0}/src/specfact_cli/commands/analyze.py

@@ -15,9 +15,11 @@ from icontract import ensure, require
 from rich.console import Console
 from rich.table import Table
 
-from specfact_cli.models.quality import CodeQuality
+from specfact_cli.models.quality import CodeQuality, QualityTracking
 from specfact_cli.telemetry import telemetry
 from specfact_cli.utils import print_error, print_success
+from specfact_cli.utils.progress import load_bundle_with_progress
+from specfact_cli.utils.structure import SpecFactStructure
 
 
 app = typer.Typer(help="Analyze codebase for contract coverage and quality")
@@ -27,7 +29,10 @@ console = Console()
 @app.command("contracts")
 @beartype
 @require(lambda repo: isinstance(repo, Path), "Repository path must be Path")
-@require(lambda bundle: isinstance(bundle, str) and len(bundle) > 0, "Bundle name must be non-empty string")
+@require(
+    lambda bundle: bundle is None or (isinstance(bundle, str) and len(bundle) > 0),
+    "Bundle name must be None or non-empty string",
+)
 @ensure(lambda result: result is None, "Must return None")
 def analyze_contracts(
     # Target/Input
@@ -57,12 +62,6 @@ def analyze_contracts(
     **Examples:**
         specfact analyze contracts --repo . --bundle legacy-api
     """
-    from rich.console import Console
-
-    from specfact_cli.models.quality import QualityTracking
-    from specfact_cli.utils.progress import load_bundle_with_progress
-    from specfact_cli.utils.structure import SpecFactStructure
-
     console = Console()
 
     # Use active plan as default if bundle not provided
@@ -119,43 +118,68 @@ def analyze_contracts(
                 if quality.crosshair:
                     files_with_crosshair += 1
 
+        # Sort files: prioritize files missing contracts
+        # Sort key: (has_all_contracts, total_contracts, file_path)
+        # This puts files missing contracts first, then by number of contracts (asc), then alphabetically
+        def sort_key(item: tuple[str, CodeQuality]) -> tuple[bool, int, str]:
+            file_path, quality = item
+            has_all = quality.beartype and quality.icontract and quality.crosshair
+            total_contracts = sum([quality.beartype, quality.icontract, quality.crosshair])
+            return (has_all, total_contracts, file_path)
+
+        sorted_files = sorted(quality_tracking.code_quality.items(), key=sort_key)
+
+        # Show files needing attention first, limit to 30 for readability
+        max_display = 30
+        files_to_display = sorted_files[:max_display]
+        total_files = len(sorted_files)
+
         # Display results
-        table = Table(title="Contract Coverage Analysis")
+        table_title = "Contract Coverage Analysis"
+        if total_files > max_display:
+            table_title += f" (showing top {max_display} files needing attention)"
+        table = Table(title=table_title)
         table.add_column("File", style="cyan")
         table.add_column("beartype", justify="center")
         table.add_column("icontract", justify="center")
         table.add_column("crosshair", justify="center")
         table.add_column("Coverage", justify="right")
 
-        for file_path, quality in list(quality_tracking.code_quality.items())[:20]:  # Show first 20
+        for file_path, quality in files_to_display:
+            # Highlight files missing contracts
+            file_style = "yellow" if not (quality.beartype and quality.icontract) else "cyan"
             table.add_row(
-                file_path,
-                "✓" if quality.beartype else "✗",
-                "✓" if quality.icontract else "✗",
-                "✓" if quality.crosshair else "✗",
+                f"[{file_style}]{file_path}[/{file_style}]",
+                "✓" if quality.beartype else "[red]✗[/red]",
+                "✓" if quality.icontract else "[red]✗[/red]",
+                "✓" if quality.crosshair else "[dim]✗[/dim]",
                 f"{quality.coverage:.0%}",
             )
 
         console.print(table)
 
+        # Show message if files were filtered
+        if total_files > max_display:
+            console.print(
+                f"\n[yellow]Note:[/yellow] Showing top {max_display} files needing attention "
+                f"(out of {total_files} total files analyzed). "
+                f"Files missing contracts are prioritized."
+            )
+
         # Summary
         console.print("\n[bold]Summary:[/bold]")
         console.print(f"  Files analyzed: {files_analyzed}")
-        console.print(
-            f"  Files with beartype: {files_with_beartype} ({files_with_beartype / files_analyzed * 100:.0%}%)"
-            if files_analyzed > 0
-            else "  Files with beartype: 0"
-        )
-        console.print(
-            f"  Files with icontract: {files_with_icontract} ({files_with_icontract / files_analyzed * 100:.0%}%)"
-            if files_analyzed > 0
-            else "  Files with icontract: 0"
-        )
-        console.print(
-            f"  Files with crosshair: {files_with_crosshair} ({files_with_crosshair / files_analyzed * 100:.0%}%)"
-            if files_analyzed > 0
-            else "  Files with crosshair: 0"
-        )
+        if files_analyzed > 0:
+            beartype_pct = files_with_beartype / files_analyzed
+            icontract_pct = files_with_icontract / files_analyzed
+            crosshair_pct = files_with_crosshair / files_analyzed
+            console.print(f"  Files with beartype: {files_with_beartype} ({beartype_pct:.1%})")
+            console.print(f"  Files with icontract: {files_with_icontract} ({icontract_pct:.1%})")
+            console.print(f"  Files with crosshair: {files_with_crosshair} ({crosshair_pct:.1%})")
+        else:
+            console.print("  Files with beartype: 0")
+            console.print("  Files with icontract: 0")
+            console.print("  Files with crosshair: 0")
 
         # Save quality tracking
         quality_file = bundle_dir / "quality-tracking.yaml"
@@ -179,9 +203,6 @@ def analyze_contracts(
 
 def _analyze_file_quality(file_path: Path) -> CodeQuality:
     """Analyze a file for contract coverage."""
-
-    from specfact_cli.models.quality import CodeQuality
-
     try:
         with file_path.open(encoding="utf-8") as f:
             content = f.read()
@@ -202,114 +223,3 @@ def _analyze_file_quality(file_path: Path) -> CodeQuality:
     except Exception:
         # Return default quality if analysis fails
         return CodeQuality()
-
-
-@app.command("enhance")
-@beartype
-@require(lambda file: isinstance(file, Path), "File path must be Path")
-@require(lambda apply: isinstance(apply, str), "Apply must be string")
-@ensure(lambda result: result is None, "Must return None")
-def enhance_contracts(
-    # Target/Input
-    file: Path = typer.Argument(..., help="Path to file to enhance", exists=True),
-    apply: str = typer.Option(
-        ...,
-        "--apply",
-        help="Contracts to apply: 'beartype', 'icontract', 'crosshair', or comma-separated list (e.g., 'beartype,icontract')",
-    ),
-    # Output
-    output: Path | None = typer.Option(
-        None,
-        "--output",
-        help="Output file path (default: overwrite input file)",
-    ),
-) -> None:
-    """
-    Apply contracts to existing code (LLM-assisted).
-
-    Prepares LLM prompt context for adding beartype, icontract, or CrossHair
-    contracts to existing code files. The CLI orchestrates, LLM writes code.
-
-    **Parameter Groups:**
-    - **Target/Input**: file (required argument), --apply
-    - **Output**: --output
-
-    **Examples:**
-        specfact enhance contracts src/auth/login.py --apply beartype,icontract
-        specfact enhance contracts src/models/user.py --apply beartype --output src/models/user_enhanced.py
-    """
-
-    file_path = file.resolve()
-    repo_path = file_path.parent.parent  # Assume repo root is 2 levels up
-
-    contracts_to_apply = [c.strip() for c in apply.split(",")]
-    valid_contracts = {"beartype", "icontract", "crosshair"}
-    invalid_contracts = set(contracts_to_apply) - valid_contracts
-
-    if invalid_contracts:
-        print_error(f"Invalid contract types: {', '.join(invalid_contracts)}")
-        print_error(f"Valid types: {', '.join(valid_contracts)}")
-        raise typer.Exit(1)
-
-    telemetry_metadata = {
-        "file": str(file_path),
-        "contracts": contracts_to_apply,
-    }
-
-    with telemetry.track_command("enhance.contracts", telemetry_metadata) as record:
-        console.print(f"[bold cyan]Enhancing contracts for:[/bold cyan] {file_path}")
-        console.print(f"[dim]Contracts to apply:[/dim] {', '.join(contracts_to_apply)}\n")
-
-        # Read file content
-        file_content = file_path.read_text(encoding="utf-8")
-
-        # Generate LLM prompt
-        prompt_parts = [
-            "# Contract Enhancement Request",
-            "",
-            f"## File: {file_path}",
-            "",
-            "## Current Code",
-            "```python",
-            file_content,
-            "```",
-            "",
-            "## Contracts to Apply",
-        ]
-
-        for contract_type in contracts_to_apply:
-            if contract_type == "beartype":
-                prompt_parts.append("- **beartype**: Add `@beartype` decorator to all functions")
-            elif contract_type == "icontract":
-                prompt_parts.append(
-                    "- **icontract**: Add `@require` and `@ensure` decorators with appropriate contracts"
-                )
-            elif contract_type == "crosshair":
-                prompt_parts.append("- **crosshair**: Add property tests using CrossHair")
-
-        prompt_parts.extend(
-            [
-                "",
-                "## Instructions",
-                "Add the requested contracts to the code above.",
-                "Maintain existing functionality and code style.",
-                "Ensure all contracts are properly imported.",
-                "",
-            ]
-        )
-
-        prompt = "\n".join(prompt_parts)
-
-        # Save prompt to file
-        prompts_dir = repo_path / ".specfact" / "prompts"
-        prompts_dir.mkdir(parents=True, exist_ok=True)
-        prompt_file = prompts_dir / f"enhance-{file_path.stem}-{'-'.join(contracts_to_apply)}.md"
-        prompt_file.write_text(prompt, encoding="utf-8")
-
-        print_success(f"LLM prompt generated: {prompt_file}")
-        console.print("[yellow]Execute this prompt with your LLM to enhance the code[/yellow]")
-
-        if output:
-            console.print(f"[dim]Output will be written to: {output}[/dim]")
-
-        record({"prompt_generated": True, "prompt_file": str(prompt_file)})

{specfact_cli-0.12.1 → specfact_cli-0.13.0}/src/specfact_cli/commands/enforce.py

@@ -318,54 +318,69 @@ def enforce_sdd(
                 console.print(f"[dim]Frozen sections: {len(sdd_manifest.frozen_sections)}[/dim]")
                 # TODO: Implement hash-based frozen section validation in Phase 6
 
-            # 4. Validate OpenAPI/AsyncAPI specs with Specmatic (if found)
-            console.print("\n[cyan]Validating API specifications...[/cyan]")
+            # 4. Validate OpenAPI/AsyncAPI contracts referenced in bundle with Specmatic
+            console.print("\n[cyan]Validating API contracts with Specmatic...[/cyan]")
             import asyncio
 
             from specfact_cli.integrations.specmatic import check_specmatic_available, validate_spec_with_specmatic
 
-            base_path = Path(".")
-            spec_files = []
-            for pattern in [
-                "**/openapi.yaml",
-                "**/openapi.yml",
-                "**/openapi.json",
-                "**/asyncapi.yaml",
-                "**/asyncapi.yml",
-                "**/asyncapi.json",
-            ]:
-                spec_files.extend(base_path.glob(pattern))
-
-            if spec_files:
-                console.print(f"[dim]Found {len(spec_files)} API specification file(s)[/dim]")
-                is_available, error_msg = check_specmatic_available()
-                if is_available:
-                    for spec_file in spec_files[:5]:  # Validate up to 5 specs
-                        console.print(f"[dim]Validating {spec_file.relative_to(base_path)} with Specmatic...[/dim]")
+            is_available, error_msg = check_specmatic_available()
+            if not is_available:
+                console.print(f"[dim]💡 Tip: Install Specmatic to validate API contracts: {error_msg}[/dim]")
+            else:
+                # Validate contracts referenced in bundle features
+                # PlanBundle.features is a list, not a dict
+                contract_files = []
+                features_iter = (
+                    plan_bundle.features.values() if isinstance(plan_bundle.features, dict) else plan_bundle.features
+                )
+                for feature in features_iter:
+                    if feature.contract:
+                        contract_path = bundle_dir / feature.contract
+                        if contract_path.exists():
+                            contract_files.append((contract_path, feature.key))
+
+                if contract_files:
+                    console.print(f"[dim]Found {len(contract_files)} contract(s) referenced in bundle[/dim]")
+                    for contract_path, feature_key in contract_files[:5]:  # Validate up to 5 contracts
+                        console.print(
+                            f"[dim]Validating {contract_path.relative_to(bundle_dir)} (from {feature_key})...[/dim]"
+                        )
                         try:
-                            result = asyncio.run(validate_spec_with_specmatic(spec_file))
+                            result = asyncio.run(validate_spec_with_specmatic(contract_path))
                             if not result.is_valid:
                                 deviation = Deviation(
                                     type=DeviationType.CONTRACT_VIOLATION,
                                     severity=DeviationSeverity.MEDIUM,
-                                    description=f"API specification validation failed: {spec_file.name}",
-                                    location=str(spec_file),
-                                    fix_hint=f"Run 'specfact spec validate {spec_file}' to see detailed errors",
+                                    description=f"API contract validation failed: {contract_path.name} (feature: {feature_key})",
+                                    location=str(contract_path),
+                                    fix_hint=f"Run 'specfact spec validate {contract_path}' to see detailed errors",
                                 )
                                 report.add_deviation(deviation)
-                                console.print(f"  [bold yellow]⚠[/bold yellow] {spec_file.name} has validation issues")
+                                console.print(
+                                    f"  [bold yellow]⚠[/bold yellow] {contract_path.name} has validation issues"
+                                )
+                                if result.errors:
+                                    for error in result.errors[:2]:
+                                        console.print(f"    - {error}")
                             else:
-                                console.print(f"  [bold green]✓[/bold green] {spec_file.name} is valid")
+                                console.print(f"  [bold green]✓[/bold green] {contract_path.name} is valid")
                         except Exception as e:
                             console.print(f"  [bold yellow]⚠[/bold yellow] Validation error: {e!s}")
-                    if len(spec_files) > 5:
+                            deviation = Deviation(
+                                type=DeviationType.CONTRACT_VIOLATION,
+                                severity=DeviationSeverity.LOW,
+                                description=f"API contract validation error: {contract_path.name} - {e!s}",
+                                location=str(contract_path),
+                                fix_hint=f"Run 'specfact spec validate {contract_path}' to diagnose",
+                            )
+                            report.add_deviation(deviation)
+                    if len(contract_files) > 5:
                         console.print(
-                            f"[dim]... and {len(spec_files) - 5} more spec file(s) (run 'specfact spec validate' to validate all)[/dim]"
+                            f"[dim]... and {len(contract_files) - 5} more contract(s) (run 'specfact spec validate' to validate all)[/dim]"
                         )
                 else:
-                    console.print(f"[dim]💡 Tip: Install Specmatic to validate API specs: {error_msg}[/dim]")
-            else:
-                console.print("[dim]No API specification files found[/dim]")
+                    console.print("[dim]No API contracts found in bundle[/dim]")
 
             # Generate output report
             output_format_str = output_format.lower()