Contract Monitoring Service

Build a Python service that continuously monitors Python source files for contract violations using automated analysis. The service should watch a directory for file changes and automatically re-analyze files when they are modified.

Requirements

File Watching

The service must monitor a specified directory for Python files and detect when files are modified. When a change is detected, the service should automatically trigger analysis of the modified file.

Contract Analysis

The service must analyze Python files to check for violations of preconditions and postconditions defined in function docstrings. The analysis should identify any inputs that would violate the specified contracts.

Results Reporting

The service must collect and report analysis results, including:

• The file that was analyzed
• Any contract violations found, with the specific line number and error message
• The timestamp when the analysis was performed

The service should output results in a structured format that can be easily consumed by other tools.

Service Control

The service must support graceful shutdown when interrupted, ensuring that any ongoing analysis completes before the service stops.

Implementation

@generates

The main implementation should include:

• A function that starts the monitoring service given a directory path
• Proper handling of the file watching mechanism
• Integration with contract checking capabilities
• Result collection and formatting

API

"""
Contract monitoring service for Python source files.
"""

from typing import Dict, List, Any

def start_monitoring(directory: str, output_file: str = "analysis_results.json") -> None:
    """
    Start monitoring a directory for Python file changes and analyze them for contract violations.

    Args:
        directory: Path to the directory to monitor
        output_file: Path to the file where analysis results will be written

    The function runs until interrupted (Ctrl+C), continuously monitoring for file changes.
    Results are written to the output file as JSON after each analysis run.
    """
    pass

def parse_analysis_results(output_file: str) -> List[Dict[str, Any]]:
    """
    Parse the analysis results from the output file.

    Args:
        output_file: Path to the results file

    Returns:
        List of analysis result dictionaries, each containing:
        - 'file': str - the file that was analyzed
        - 'violations': List[Dict] - list of violations found, each with 'line' and 'message'
        - 'timestamp': str - when the analysis was performed (ISO format)
    """
    pass

Test Cases

Basic monitoring functionality { .test-group }

• Given a directory with a Python file containing a function with a failing precondition contract in its docstring, when the monitoring service is started and the file is modified, then the service detects the violation and reports it with the correct file path and line number @test

• Given a directory with a Python file containing a function with a failing postcondition contract in its docstring, when the file is created after the monitoring service starts, then the service analyzes the new file and reports the postcondition violation @test

• Given an empty directory being monitored, when a Python file with valid contracts is added, then the service analyzes it and reports no violations @test

Dependencies { .dependencies }

crosshair-tool { .dependency }

Provides symbolic execution and contract verification for Python code, including file watching capabilities.

@satisfied-by