cognitive-modules 0.3.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

cognitive/validator.py

@@ -1,11 +1,11 @@
 """
 Module Validator - Validate cognitive module structure and examples.
-Supports both old and new module formats.
+Supports v0, v1, v2.1, and v2.2 module formats.
 """
 
 import json
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Literal
 
 import jsonschema
 import yaml
@@ -13,10 +13,21 @@ import yaml
 from .registry import find_module
 
 
-def validate_module(name_or_path: str) -> tuple[bool, list[str], list[str]]:
+# =============================================================================
+# Main Validation Entry Point
+# =============================================================================
+
+def validate_module(
+    name_or_path: str,
+    v22: bool = False
+) -> tuple[bool, list[str], list[str]]:
     """
     Validate a cognitive module's structure and examples.
-    Supports both old and new formats.
+    Supports all formats.
+    
+    Args:
+        name_or_path: Module name or path
+        v22: If True, validate v2.2 specific requirements
     
     Returns:
         Tuple of (is_valid, errors, warnings)
@@ -34,22 +45,256 @@ def validate_module(name_or_path: str) -> tuple[bool, list[str], list[str]]:
             return False, [f"Module not found: {name_or_path}"], []
     
     # Detect format
-    has_new = (module_path / "MODULE.md").exists()
-    has_old = (module_path / "module.md").exists()
+    has_module_yaml = (module_path / "module.yaml").exists()
+    has_module_md = (module_path / "MODULE.md").exists()
+    has_old_module_md = (module_path / "module.md").exists()
+    
+    if has_module_yaml:
+        # v2.x format
+        if v22:
+            return _validate_v22_format(module_path)
+        else:
+            return _validate_v2_format(module_path)
+    elif has_module_md:
+        # v1 format
+        if v22:
+            errors.append("Module is v1 format. Use 'cogn migrate' to upgrade to v2.2")
+            return False, errors, warnings
+        return _validate_new_format(module_path)
+    elif has_old_module_md:
+        # v0 format
+        if v22:
+            errors.append("Module is v0 format. Use 'cogn migrate' to upgrade to v2.2")
+            return False, errors, warnings
+        return _validate_old_format(module_path)
+    else:
+        return False, ["Missing module.yaml, MODULE.md, or module.md"], []
+
+
+# =============================================================================
+# v2.2 Validation
+# =============================================================================
+
+def _validate_v22_format(module_path: Path) -> tuple[bool, list[str], list[str]]:
+    """Validate v2.2 format (module.yaml + prompt.md + schema.json with meta)."""
+    errors = []
+    warnings = []
     
-    if not has_new and not has_old:
-        return False, ["Missing MODULE.md or module.md"], []
+    # Check module.yaml
+    module_yaml = module_path / "module.yaml"
+    try:
+        with open(module_yaml, 'r', encoding='utf-8') as f:
+            manifest = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        errors.append(f"Invalid YAML in module.yaml: {e}")
+        return False, errors, warnings
     
-    format_type = "new" if has_new else "old"
+    # Check v2.2 required fields
+    v22_required_fields = ['name', 'version', 'responsibility']
+    for field in v22_required_fields:
+        if field not in manifest:
+            errors.append(f"module.yaml missing required field: {field}")
     
-    if format_type == "new":
-        return _validate_new_format(module_path)
+    # Check tier (v2.2 specific)
+    tier = manifest.get('tier')
+    if tier is None:
+        warnings.append("module.yaml missing 'tier' (recommended: exec | decision | exploration)")
+    elif tier not in ['exec', 'decision', 'exploration']:
+        errors.append(f"Invalid tier: {tier}. Must be exec | decision | exploration")
+    
+    # Check schema_strictness
+    schema_strictness = manifest.get('schema_strictness')
+    if schema_strictness and schema_strictness not in ['high', 'medium', 'low']:
+        errors.append(f"Invalid schema_strictness: {schema_strictness}. Must be high | medium | low")
+    
+    # Check overflow config
+    overflow = manifest.get('overflow', {})
+    if overflow.get('enabled'):
+        if overflow.get('require_suggested_mapping') is None:
+            warnings.append("overflow.require_suggested_mapping not set (recommended for recoverable insights)")
+    
+    # Check enums config
+    enums = manifest.get('enums', {})
+    strategy = enums.get('strategy')
+    if strategy and strategy not in ['strict', 'extensible']:
+        errors.append(f"Invalid enums.strategy: {strategy}. Must be strict | extensible")
+    
+    # Check compat config
+    compat = manifest.get('compat', {})
+    if not compat:
+        warnings.append("module.yaml missing 'compat' section (recommended for migration)")
+    
+    # Check excludes
+    excludes = manifest.get('excludes', [])
+    if not excludes:
+        warnings.append("'excludes' list is empty (should list what module won't do)")
+    
+    # Check prompt.md
+    prompt_path = module_path / "prompt.md"
+    if not prompt_path.exists():
+        errors.append("Missing prompt.md (required for v2.2)")
     else:
-        return _validate_old_format(module_path)
+        with open(prompt_path, 'r', encoding='utf-8') as f:
+            prompt = f.read()
+        
+        # Check for v2.2 envelope format instructions
+        if 'meta' not in prompt.lower() and 'envelope' not in prompt.lower():
+            warnings.append("prompt.md should mention v2.2 envelope format with meta/data separation")
+        
+        if len(prompt) < 100:
+            warnings.append("prompt.md seems too short (< 100 chars)")
+    
+    # Check schema.json
+    schema_path = module_path / "schema.json"
+    if not schema_path.exists():
+        errors.append("Missing schema.json (required for v2.2)")
+    else:
+        try:
+            with open(schema_path, 'r', encoding='utf-8') as f:
+                schema = json.load(f)
+            
+            # Check for meta schema (v2.2 required)
+            if 'meta' not in schema:
+                errors.append("schema.json missing 'meta' schema (required for v2.2)")
+            else:
+                meta_schema = schema['meta']
+                meta_required = meta_schema.get('required', [])
+                
+                if 'confidence' not in meta_required:
+                    errors.append("meta schema must require 'confidence'")
+                if 'risk' not in meta_required:
+                    errors.append("meta schema must require 'risk'")
+                if 'explain' not in meta_required:
+                    errors.append("meta schema must require 'explain'")
+                
+                # Check explain maxLength
+                explain_props = meta_schema.get('properties', {}).get('explain', {})
+                if explain_props.get('maxLength', 999) > 280:
+                    warnings.append("meta.explain should have maxLength <= 280")
+            
+            # Check for input schema
+            if 'input' not in schema:
+                warnings.append("schema.json missing 'input' definition")
+            
+            # Check for data schema (v2.2 uses 'data' instead of 'output')
+            if 'data' not in schema and 'output' not in schema:
+                errors.append("schema.json missing 'data' (or 'output') definition")
+            elif 'data' in schema:
+                data_schema = schema['data']
+                data_required = data_schema.get('required', [])
+                
+                if 'rationale' not in data_required:
+                    warnings.append("data schema should require 'rationale' for audit")
+            
+            # Check for error schema
+            if 'error' not in schema:
+                warnings.append("schema.json missing 'error' definition")
+            
+            # Check for $defs/extensions (v2.2 overflow)
+            if overflow.get('enabled'):
+                defs = schema.get('$defs', {})
+                if 'extensions' not in defs:
+                    warnings.append("schema.json missing '$defs.extensions' (needed for overflow)")
+                    
+        except json.JSONDecodeError as e:
+            errors.append(f"Invalid JSON in schema.json: {e}")
+    
+    # Check tests directory
+    tests_path = module_path / "tests"
+    if not tests_path.exists():
+        warnings.append("Missing tests directory (recommended)")
+    else:
+        # Check for v2.2 format in expected files
+        expected_files = list(tests_path.glob("*.expected.json"))
+        for expected_file in expected_files:
+            try:
+                with open(expected_file, 'r', encoding='utf-8') as f:
+                    expected = json.load(f)
+                
+                # Check if example uses v2.2 format
+                example = expected.get('$example', {})
+                if example.get('ok') is True and 'meta' not in example:
+                    warnings.append(f"{expected_file.name}: $example missing 'meta' (v2.2 format)")
+                    
+            except json.JSONDecodeError:
+                pass
+    
+    return len(errors) == 0, errors, warnings
+
+
+# =============================================================================
+# v2.x (non-strict) Validation
+# =============================================================================
+
+def _validate_v2_format(module_path: Path) -> tuple[bool, list[str], list[str]]:
+    """Validate v2.x format without strict v2.2 requirements."""
+    errors = []
+    warnings = []
+    
+    # Check module.yaml
+    module_yaml = module_path / "module.yaml"
+    try:
+        with open(module_yaml, 'r', encoding='utf-8') as f:
+            manifest = yaml.safe_load(f)
+    except yaml.YAMLError as e:
+        errors.append(f"Invalid YAML in module.yaml: {e}")
+        return False, errors, warnings
+    
+    # Check required fields
+    required_fields = ['name', 'version', 'responsibility']
+    for field in required_fields:
+        if field not in manifest:
+            errors.append(f"module.yaml missing required field: {field}")
+    
+    # Check excludes
+    excludes = manifest.get('excludes', [])
+    if not excludes:
+        warnings.append("'excludes' list is empty")
+    
+    # Check prompt.md or prompt existence in MODULE.md
+    prompt_path = module_path / "prompt.md"
+    module_md_path = module_path / "MODULE.md"
+    
+    if not prompt_path.exists() and not module_md_path.exists():
+        errors.append("Missing prompt.md or MODULE.md")
+    elif prompt_path.exists():
+        with open(prompt_path, 'r', encoding='utf-8') as f:
+            prompt = f.read()
+        if len(prompt) < 50:
+            warnings.append("prompt.md seems too short (< 50 chars)")
+    
+    # Check schema.json
+    schema_path = module_path / "schema.json"
+    if not schema_path.exists():
+        warnings.append("Missing schema.json (recommended)")
+    else:
+        try:
+            with open(schema_path, 'r', encoding='utf-8') as f:
+                schema = json.load(f)
+            
+            if 'input' not in schema:
+                warnings.append("schema.json missing 'input' definition")
+            
+            # Accept both 'data' and 'output'
+            if 'data' not in schema and 'output' not in schema:
+                warnings.append("schema.json missing 'data' or 'output' definition")
+                
+        except json.JSONDecodeError as e:
+            errors.append(f"Invalid JSON in schema.json: {e}")
+    
+    # Check for v2.2 features and suggest upgrade
+    if manifest.get('tier') is None:
+        warnings.append("Consider adding 'tier' for v2.2 (use 'cogn validate --v22' for full check)")
+    
+    return len(errors) == 0, errors, warnings
 
 
+# =============================================================================
+# v1 Format Validation (MODULE.md + schema.json)
+# =============================================================================
+
 def _validate_new_format(module_path: Path) -> tuple[bool, list[str], list[str]]:
-    """Validate new format (MODULE.md + schema.json)."""
+    """Validate v1 format (MODULE.md + schema.json)."""
     errors = []
     warnings = []
     
@@ -93,7 +338,7 @@ def _validate_new_format(module_path: Path) -> tuple[bool, list[str], list[str]]
     except yaml.YAMLError as e:
         errors.append(f"Invalid YAML in MODULE.md: {e}")
     
-    # Check schema.json (optional but recommended)
+    # Check schema.json
     schema_path = module_path / "schema.json"
     if not schema_path.exists():
         warnings.append("Missing schema.json (recommended for validation)")
@@ -118,56 +363,25 @@ def _validate_new_format(module_path: Path) -> tuple[bool, list[str], list[str]]
         except json.JSONDecodeError as e:
             errors.append(f"Invalid JSON in schema.json: {e}")
     
-    # Check examples (optional but recommended)
+    # Check examples
     examples_path = module_path / "examples"
     if not examples_path.exists():
         warnings.append("Missing examples directory (recommended)")
     else:
-        if not (examples_path / "input.json").exists():
-            warnings.append("Missing examples/input.json")
-        if not (examples_path / "output.json").exists():
-            warnings.append("Missing examples/output.json")
-        
-        # Validate examples against schema if both exist
-        if schema_path.exists():
-            try:
-                with open(schema_path, 'r', encoding='utf-8') as f:
-                    schema = json.load(f)
-                
-                # Validate input example
-                input_example_path = examples_path / "input.json"
-                if input_example_path.exists() and "input" in schema:
-                    with open(input_example_path, 'r', encoding='utf-8') as f:
-                        input_example = json.load(f)
-                    try:
-                        jsonschema.validate(instance=input_example, schema=schema["input"])
-                    except jsonschema.ValidationError as e:
-                        errors.append(f"Example input fails schema: {e.message}")
-                
-                # Validate output example
-                output_example_path = examples_path / "output.json"
-                if output_example_path.exists() and "output" in schema:
-                    with open(output_example_path, 'r', encoding='utf-8') as f:
-                        output_example = json.load(f)
-                    try:
-                        jsonschema.validate(instance=output_example, schema=schema["output"])
-                    except jsonschema.ValidationError as e:
-                        errors.append(f"Example output fails schema: {e.message}")
-                    
-                    # Check confidence
-                    if "confidence" in output_example:
-                        conf = output_example["confidence"]
-                        if not (0 <= conf <= 1):
-                            errors.append(f"Confidence must be 0-1, got: {conf}")
-                            
-            except (json.JSONDecodeError, KeyError):
-                pass
+        _validate_examples(examples_path, schema_path, errors, warnings)
+    
+    # Suggest v2.2 upgrade
+    warnings.append("Consider upgrading to v2.2 format for better Control/Data separation")
     
     return len(errors) == 0, errors, warnings
 
 
+# =============================================================================
+# v0 Format Validation (6-file format)
+# =============================================================================
+
 def _validate_old_format(module_path: Path) -> tuple[bool, list[str], list[str]]:
-    """Validate old format (6 files)."""
+    """Validate v0 format (6 files)."""
     errors = []
     warnings = []
     
@@ -226,77 +440,121 @@ def _validate_old_format(module_path: Path) -> tuple[bool, list[str], list[str]]
     except yaml.YAMLError as e:
         errors.append(f"Invalid YAML in module.md: {e}")
     
-    # Load and validate schemas
-    input_schema = None
-    output_schema = None
+    # Suggest v2.2 upgrade
+    warnings.append("v0 format is deprecated. Consider upgrading to v2.2")
     
-    try:
-        with open(module_path / "input.schema.json", 'r', encoding='utf-8') as f:
-            input_schema = json.load(f)
-        if input_schema.get('additionalProperties') != False:
-            warnings.append("input.schema.json should have additionalProperties: false")
-    except json.JSONDecodeError as e:
-        errors.append(f"Invalid JSON in input.schema.json: {e}")
+    return len(errors) == 0, errors, warnings
+
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+def _validate_examples(
+    examples_path: Path,
+    schema_path: Path,
+    errors: list[str],
+    warnings: list[str]
+) -> None:
+    """Validate example files against schema."""
+    if not (examples_path / "input.json").exists():
+        warnings.append("Missing examples/input.json")
+    if not (examples_path / "output.json").exists():
+        warnings.append("Missing examples/output.json")
     
-    try:
-        with open(module_path / "output.schema.json", 'r', encoding='utf-8') as f:
-            output_schema = json.load(f)
-        required_output_fields = ['confidence', 'rationale']
-        if 'required' in output_schema:
-            for field in required_output_fields:
-                if field not in output_schema['required']:
-                    warnings.append(f"output.schema.json should require '{field}'")
-    except json.JSONDecodeError as e:
-        errors.append(f"Invalid JSON in output.schema.json: {e}")
-    
-    # Validate constraints
-    try:
-        with open(module_path / "constraints.yaml", 'r', encoding='utf-8') as f:
-            constraints = yaml.safe_load(f)
+    # Validate examples against schema if both exist
+    if schema_path.exists():
+        try:
+            with open(schema_path, 'r', encoding='utf-8') as f:
+                schema = json.load(f)
+            
+            # Validate input example
+            input_example_path = examples_path / "input.json"
+            if input_example_path.exists() and "input" in schema:
+                with open(input_example_path, 'r', encoding='utf-8') as f:
+                    input_example = json.load(f)
+                try:
+                    jsonschema.validate(instance=input_example, schema=schema["input"])
+                except jsonschema.ValidationError as e:
+                    errors.append(f"Example input fails schema: {e.message}")
+            
+            # Validate output example
+            output_example_path = examples_path / "output.json"
+            output_schema = schema.get("output", schema.get("data"))
+            if output_example_path.exists() and output_schema:
+                with open(output_example_path, 'r', encoding='utf-8') as f:
+                    output_example = json.load(f)
+                try:
+                    jsonschema.validate(instance=output_example, schema=output_schema)
+                except jsonschema.ValidationError as e:
+                    errors.append(f"Example output fails schema: {e.message}")
+                
+                # Check confidence
+                if "confidence" in output_example:
+                    conf = output_example["confidence"]
+                    if not (0 <= conf <= 1):
+                        errors.append(f"Confidence must be 0-1, got: {conf}")
+                        
+        except (json.JSONDecodeError, KeyError):
+            pass
+
+
+def validate_v22_envelope(response: dict) -> tuple[bool, list[str]]:
+    """
+    Validate a response against v2.2 envelope format.
+    
+    Args:
+        response: The response dict to validate
         
-        required_constraints = ['no_external_network', 'no_side_effects', 'no_inventing_data']
-        if 'operational' in constraints:
-            for constraint in required_constraints:
-                if constraint not in constraints['operational']:
-                    warnings.append(f"Missing operational constraint: {constraint}")
-                elif not constraints['operational'][constraint]:
-                    warnings.append(f"Constraint '{constraint}' is set to false")
-        else:
-            warnings.append("Missing 'operational' section in constraints")
-    except yaml.YAMLError as e:
-        errors.append(f"Invalid YAML in constraints.yaml: {e}")
+    Returns:
+        Tuple of (is_valid, errors)
+    """
+    errors = []
     
-    # Check prompt.txt
-    with open(module_path / "prompt.txt", 'r', encoding='utf-8') as f:
-        prompt = f.read()
-    if len(prompt) < 100:
-        warnings.append("prompt.txt seems too short (< 100 chars)")
+    # Check ok field
+    if 'ok' not in response:
+        errors.append("Missing 'ok' field")
+        return False, errors
     
-    # Validate example input against schema
-    if input_schema:
-        try:
-            with open(examples_path / "input.json", 'r', encoding='utf-8') as f:
-                example_input = json.load(f)
-            jsonschema.validate(instance=example_input, schema=input_schema)
-        except json.JSONDecodeError as e:
-            errors.append(f"Invalid JSON in examples/input.json: {e}")
-        except jsonschema.ValidationError as e:
-            errors.append(f"Example input fails schema validation: {e.message}")
+    # Check meta
+    if 'meta' not in response:
+        errors.append("Missing 'meta' field (required for v2.2)")
+    else:
+        meta = response['meta']
+        
+        if 'confidence' not in meta:
+            errors.append("meta missing 'confidence'")
+        elif not isinstance(meta['confidence'], (int, float)):
+            errors.append("meta.confidence must be a number")
+        elif not (0 <= meta['confidence'] <= 1):
+            errors.append("meta.confidence must be between 0 and 1")
+        
+        if 'risk' not in meta:
+            errors.append("meta missing 'risk'")
+        elif meta['risk'] not in ['none', 'low', 'medium', 'high']:
+            errors.append(f"meta.risk must be none|low|medium|high, got: {meta['risk']}")
+        
+        if 'explain' not in meta:
+            errors.append("meta missing 'explain'")
+        elif len(meta.get('explain', '')) > 280:
+            errors.append(f"meta.explain exceeds 280 chars ({len(meta['explain'])} chars)")
     
-    # Validate example output against schema
-    if output_schema:
-        try:
-            with open(examples_path / "output.json", 'r', encoding='utf-8') as f:
-                example_output = json.load(f)
-            jsonschema.validate(instance=example_output, schema=output_schema)
-            
-            if 'confidence' in example_output:
-                conf = example_output['confidence']
-                if not (0 <= conf <= 1):
-                    errors.append(f"Confidence must be between 0 and 1, got: {conf}")
-        except json.JSONDecodeError as e:
-            errors.append(f"Invalid JSON in examples/output.json: {e}")
-        except jsonschema.ValidationError as e:
-            errors.append(f"Example output fails schema validation: {e.message}")
+    # Check data or error
+    if response['ok']:
+        if 'data' not in response:
+            errors.append("Success response missing 'data' field")
+        else:
+            data = response['data']
+            if 'rationale' not in data:
+                errors.append("data missing 'rationale' (recommended for audit)")
+    else:
+        if 'error' not in response:
+            errors.append("Error response missing 'error' field")
+        else:
+            error = response['error']
+            if 'code' not in error:
+                errors.append("error missing 'code'")
+            if 'message' not in error:
+                errors.append("error missing 'message'")
     
-    return len(errors) == 0, errors, warnings
+    return len(errors) == 0, errors