ostruct-cli 0.4.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

ostruct/cli/file_utils.py

@@ -46,13 +46,14 @@ import codecs
 import glob
 import logging
 import os
-from typing import Any, Dict, List, Optional, Type, Union
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Type, Union
 
 import chardet
 
 from .errors import (
     DirectoryNotFoundError,
-    FileNotFoundError,
+    OstructFileNotFoundError,
     PathSecurityError,
 )
 from .file_info import FileInfo
@@ -113,10 +114,10 @@ def collect_files_from_pattern(
     pattern: str,
     security_manager: SecurityManager,
 ) -> List[FileInfo]:
-    """Collect files matching a glob pattern.
+    """Collect files matching a glob pattern or exact file path.
 
     Args:
-        pattern: Glob pattern to match files
+        pattern: Glob pattern or file path to match
         security_manager: Security manager for path validation
 
     Returns:
@@ -125,7 +126,18 @@ def collect_files_from_pattern(
     Raises:
         PathSecurityError: If any matched file is outside base directory
     """
-    # Expand pattern
+    # First check if it's an exact file path
+    if os.path.isfile(pattern):
+        try:
+            file_info = FileInfo.from_path(pattern, security_manager)
+            return [file_info]
+        except PathSecurityError:
+            raise
+        except Exception as e:
+            logger.warning("Could not process file %s: %s", pattern, str(e))
+            return []
+
+    # If not an exact file, try glob pattern
     matched_paths = glob.glob(pattern, recursive=True)
     if not matched_paths:
         logger.debug("No files matched pattern: %s", pattern)
@@ -140,8 +152,8 @@ def collect_files_from_pattern(
         except PathSecurityError:
             # Let security errors propagate
             raise
-        except Exception:
-            logger.warning("Could not process file %s", path)
+        except Exception as e:
+            logger.warning("Could not process file %s: %s", path, str(e))
 
     return files
 
@@ -256,20 +268,21 @@ def collect_files_from_directory(
                     raise
 
                 try:
+                    # Use absolute path when creating FileInfo
                     file_info = FileInfo.from_path(
-                        rel_path, security_manager=security_manager, **kwargs
+                        abs_path, security_manager=security_manager, **kwargs
                     )
                     files.append(file_info)
-                    logger.debug("Added file to list: %s", rel_path)
+                    logger.debug("Added file to list: %s", abs_path)
                 except PathSecurityError as e:
                     # Log and re-raise security errors immediately
                     logger.error(
                         "Security violation processing file: %s (%s)",
-                        rel_path,
+                        abs_path,
                         str(e),
                     )
                     raise
-                except (FileNotFoundError, PermissionError) as e:
+                except (OstructFileNotFoundError, PermissionError) as e:
                     # Skip legitimate file access errors
                     logger.warning(
                         "Skipping inaccessible file: %s (error: %s)",
@@ -289,39 +302,34 @@ def collect_files_from_directory(
 
 
 def _validate_and_split_mapping(
-    mapping: str, mapping_type: str
+    mapping: tuple[str, Union[str, Path]], mapping_type: str
 ) -> tuple[str, str]:
-    """Validate and split a name=value mapping.
+    """Validate a name/path tuple mapping.
 
     Args:
-        mapping: The mapping string to validate (e.g. "name=value")
+        mapping: The mapping tuple (name, path)
         mapping_type: Type of mapping for error messages ("file", "pattern", or "directory")
 
     Returns:
-        Tuple of (name, value)
+        The same tuple of (name, path)
 
     Raises:
         ValueError: If mapping format is invalid
     """
-    try:
-        name, value = mapping.split("=", 1)
-    except ValueError:
-        raise ValueError(
-            f"Invalid {mapping_type} mapping format: {mapping!r} (missing '=' separator)"
-        )
+    name, value = mapping
 
     if not name:
-        raise ValueError(f"Empty name in {mapping_type} mapping: {mapping!r}")
+        raise ValueError(f"Empty name in {mapping_type} mapping")
     if not value:
-        raise ValueError(f"Empty value in {mapping_type} mapping: {mapping!r}")
+        raise ValueError(f"Empty value in {mapping_type} mapping")
 
-    return name, value
+    return name, str(value)  # Convert Path to str if needed
 
 
 def collect_files(
-    file_mappings: Optional[List[str]] = None,
-    pattern_mappings: Optional[List[str]] = None,
-    dir_mappings: Optional[List[str]] = None,
+    file_mappings: Optional[List[Tuple[str, Union[str, Path]]]] = None,
+    pattern_mappings: Optional[List[Tuple[str, Union[str, Path]]]] = None,
+    dir_mappings: Optional[List[Tuple[str, Union[str, Path]]]] = None,
     dir_recursive: bool = False,
     dir_extensions: Optional[List[str]] = None,
     security_manager: Optional[SecurityManager] = None,
@@ -330,9 +338,9 @@ def collect_files(
     """Collect files from multiple sources.
 
     Args:
-        file_mappings: List of file mappings in the format "name=path"
-        pattern_mappings: List of pattern mappings in the format "name=pattern"
-        dir_mappings: List of directory mappings in the format "name=directory"
+        file_mappings: List of file mappings as (name, path) tuples
+        pattern_mappings: List of pattern mappings as (name, pattern) tuples
+        dir_mappings: List of directory mappings as (name, directory) tuples
         dir_recursive: Whether to process directories recursively
         dir_extensions: List of file extensions to include in directory processing
         security_manager: Security manager instance
@@ -383,7 +391,7 @@ def collect_files(
                 raise ValueError(f"Duplicate file mapping: {name}")
 
             file_info = FileInfo.from_path(
-                path, security_manager=security_manager, **kwargs
+                str(path), security_manager=security_manager, **kwargs
             )
             files[name] = FileInfoList([file_info], from_dir=False)
             logger.debug("Added single file mapping: %s -> %s", name, path)
@@ -398,7 +406,7 @@ def collect_files(
 
             try:
                 matched_files = collect_files_from_pattern(
-                    pattern, security_manager=security_manager, **kwargs
+                    str(pattern), security_manager=security_manager, **kwargs
                 )
             except PathSecurityError as e:
                 logger.debug("Security error in pattern mapping: %s", str(e))
@@ -465,7 +473,7 @@ def collect_files(
 
     if not files:
         logger.debug("No files found in any mappings")
-        raise ValueError("No files found")
+        return files
 
     logger.debug("Collected files total mappings: %d", len(files))
     return files
@@ -609,14 +617,14 @@ def read_allowed_dirs_from_file(filepath: str) -> List[str]:
         A list of allowed directories as absolute paths.
 
     Raises:
-        FileNotFoundError: If the file does not exist.
+        OstructFileNotFoundError: If the file does not exist.
         ValueError: If the file contains invalid data.
     """
     try:
         with open(filepath, "r") as f:
             lines = f.readlines()
     except OSError as e:
-        raise FileNotFoundError(
+        raise OstructFileNotFoundError(
             f"Error reading allowed directories from file: {filepath}: {e}"
         )
 

ostruct/cli/path_utils.py

@@ -1,17 +1,21 @@
 """Path validation utilities for the CLI."""
 
+import logging
 from pathlib import Path
 from typing import Optional, Tuple
 
 from ostruct.cli.errors import (
     DirectoryNotFoundError,
-    FileNotFoundError,
+    OstructFileNotFoundError,
+    PathSecurityError,
     VariableNameError,
     VariableValueError,
 )
-from ostruct.cli.security.errors import PathSecurityError, SecurityErrorReasons
+from ostruct.cli.security.errors import SecurityErrorReasons
 from ostruct.cli.security.security_manager import SecurityManager
 
+logger = logging.getLogger(__name__)
+
 
 def validate_path_mapping(
     mapping: str,
@@ -44,34 +48,52 @@ def validate_path_mapping(
         >>> validate_path_mapping("data=config/", is_dir=True)  # Validates directory
         ('data', 'config/')
     """
+    logger.debug(
+        "Validating path mapping: %s (is_dir=%s, base_dir=%s)",
+        mapping,
+        is_dir,
+        base_dir,
+    )
+
     # Split into name and path parts
     try:
         name, path_str = mapping.split("=", 1)
     except ValueError:
+        logger.error("Invalid mapping format (missing '='): %s", mapping)
         raise ValueError(f"Invalid mapping format (missing '='): {mapping}")
 
     # Validate name
     name = name.strip()
     if not name:
+        logger.error("Variable name cannot be empty: %s", mapping)
         raise VariableNameError("Variable name cannot be empty")
     if not name.isidentifier():
+        logger.error("Invalid variable name: %s", name)
         raise VariableNameError(f"Invalid variable name: {name}")
 
     # Normalize path
     path_str = path_str.strip()
     if not path_str:
+        logger.error("Path cannot be empty: %s", mapping)
         raise VariableValueError("Path cannot be empty")
 
+    logger.debug("Creating Path object for: %s", path_str)
     # Create a Path object
     path = Path(path_str)
     if not path.is_absolute() and base_dir:
+        logger.debug(
+            "Converting relative path to absolute using base_dir: %s", base_dir
+        )
         path = Path(base_dir) / path
 
     # Validate path with security manager if provided
     if security_manager:
+        logger.debug("Validating path with security manager: %s", path)
         try:
             path = security_manager.validate_path(path)
+            logger.debug("Security validation passed: %s", path)
         except PathSecurityError as e:
+            logger.error("Security validation failed: %s - %s", path, e)
             if (
                 e.context.get("reason")
                 == SecurityErrorReasons.PATH_OUTSIDE_ALLOWED
@@ -89,16 +111,22 @@ def validate_path_mapping(
 
     # Check path existence and type
     if not path.exists():
+        logger.error("Path does not exist: %s", path)
         if is_dir:
             raise DirectoryNotFoundError(f"Directory not found: {path}")
-        raise FileNotFoundError(f"File not found: {path}")
+        raise OstructFileNotFoundError(f"File not found: {path}")
 
     # Check path type
     if is_dir and not path.is_dir():
+        logger.error("Path exists but is not a directory: %s", path)
         raise DirectoryNotFoundError(
             f"Path exists but is not a directory: {path}"
         )
     elif not is_dir and not path.is_file():
-        raise FileNotFoundError(f"Path exists but is not a file: {path}")
+        logger.error("Path exists but is not a file: %s", path)
+        raise OstructFileNotFoundError(
+            f"Path exists but is not a file: {path}"
+        )
 
+    logger.debug("Path validation successful: %s -> %s", name, path)
     return name, str(path)

ostruct/cli/schema_validation.py

@@ -0,0 +1,213 @@
+from enum import IntEnum
+from typing import Any, Dict, List, Optional
+
+from .errors import SchemaValidationError
+
+
+class SchemaLimits(IntEnum):
+    """Limits for OpenAI schema validation."""
+
+    MAX_NESTING_DEPTH = 5
+    MAX_PROPERTIES = 100
+    MAX_ENUM_VALUES = 500
+    MAX_ENUM_VALUES_CHAR_CHECK = 250
+    MAX_ENUM_TOTAL_CHARS = 7500
+
+
+# Validates the schema against OpenAI's structured output requirements.
+# https://platform.openai.com/docs/guides/structured-outputs
+
+
+def validate_openai_schema(
+    schema: Dict[str, Any], path: Optional[List[str]] = None
+) -> None:
+    """Validate schema against OpenAI's structured output requirements.
+
+    Args:
+        schema: The JSON schema to validate
+        path: Current path in schema for nested validation
+
+    Raises:
+        SchemaValidationError: If schema violates any OpenAI requirements
+    """
+    path = path or []
+    current_path = "/".join(path) or "<root>"
+
+    # Root level validation
+    if not path:  # Only check at root
+        if schema.get("type") != "object":
+            raise SchemaValidationError(
+                "Root schema must be type 'object'",
+                context={
+                    "path": current_path,
+                    "found": schema.get("type"),
+                    "tips": [
+                        "The root of your schema must be an object type",
+                        "If you have an array, wrap it in an object property:",
+                        {
+                            "type": "object",
+                            "properties": {
+                                "items": {
+                                    "type": "array",
+                                    "items": "...your array schema...",
+                                }
+                            },
+                            "required": ["items"],
+                            "additionalProperties": False,
+                        },
+                    ],
+                },
+            )
+
+        if schema.get("additionalProperties") is not False:
+            raise SchemaValidationError(
+                "Root schema must set additionalProperties: false",
+                context={
+                    "path": current_path,
+                    "tips": [
+                        "Add 'additionalProperties: false' to your root schema",
+                        "This ensures only defined properties are allowed",
+                    ],
+                },
+            )
+
+        # Validate required properties
+        root_properties = set(schema.get("properties", {}).keys())
+        required = set(schema.get("required", []))
+
+        if not root_properties:
+            raise SchemaValidationError(
+                "Root schema must define at least one property",
+                context={
+                    "path": current_path,
+                    "tips": [
+                        "Add properties to your schema",
+                        "Each property should define its type and any constraints",
+                    ],
+                },
+            )
+
+        if required != root_properties:
+            missing = root_properties - required
+            extra = required - root_properties
+            tips = []
+            if missing:
+                tips.append(
+                    f"Add these properties to 'required': {list(missing)}"
+                )
+            if extra:
+                tips.append(
+                    f"Remove these from 'required' as they aren't defined: {list(extra)}"
+                )
+
+            raise SchemaValidationError(
+                "All properties must be required in root schema",
+                context={
+                    "path": current_path,
+                    "missing_required": list(missing),
+                    "extra_required": list(extra),
+                    "tips": tips,
+                },
+            )
+
+    # Structural validation
+    if len(path) > SchemaLimits.MAX_NESTING_DEPTH:
+        raise SchemaValidationError(
+            f"Schema exceeds maximum nesting depth of {SchemaLimits.MAX_NESTING_DEPTH} levels",
+            context={
+                "path": current_path,
+                "tips": [
+                    "Flatten your schema structure",
+                    "Consider combining nested objects",
+                    "Move complex structures to root level properties",
+                ],
+            },
+        )
+
+    # Property count validation
+    if schema.get("type") == "object":
+        obj_properties: Dict[str, Any] = schema.get("properties", {})
+        if len(obj_properties) > SchemaLimits.MAX_PROPERTIES:
+            raise SchemaValidationError(
+                f"Schema exceeds maximum of {SchemaLimits.MAX_PROPERTIES} properties",
+                context={
+                    "path": current_path,
+                    "count": len(obj_properties),
+                    "tips": [
+                        "Reduce the number of properties",
+                        "Consider grouping related properties into sub-objects",
+                        "Remove any unused or optional properties",
+                    ],
+                },
+            )
+
+        # Validate each property
+        for prop_name, prop_schema in obj_properties.items():
+            validate_openai_schema(prop_schema, path + [prop_name])
+
+    # Array validation
+    elif schema.get("type") == "array":
+        if "items" in schema:
+            validate_openai_schema(schema["items"], path + ["items"])
+
+    # Enum validation
+    if "enum" in schema:
+        enum_values = schema["enum"]
+        if len(enum_values) > SchemaLimits.MAX_ENUM_VALUES:
+            raise SchemaValidationError(
+                f"Enum exceeds maximum of {SchemaLimits.MAX_ENUM_VALUES} values",
+                context={
+                    "path": current_path,
+                    "count": len(enum_values),
+                    "tips": [
+                        "Reduce the number of enum values",
+                        "Consider using a different type or structure",
+                        "Split into multiple smaller enums if possible",
+                    ],
+                },
+            )
+
+        # Check enum string length for large enums
+        if len(enum_values) > SchemaLimits.MAX_ENUM_VALUES_CHAR_CHECK:
+            total_chars = sum(len(str(v)) for v in enum_values)
+            if total_chars > SchemaLimits.MAX_ENUM_TOTAL_CHARS:
+                raise SchemaValidationError(
+                    f"Enum values exceed maximum total length of {SchemaLimits.MAX_ENUM_TOTAL_CHARS} characters",
+                    context={
+                        "path": current_path,
+                        "total_chars": total_chars,
+                        "tips": [
+                            "Reduce the length of enum values",
+                            "Consider using shorter identifiers",
+                            "Split into multiple smaller enums",
+                        ],
+                    },
+                )
+
+    # Prohibited keywords by type
+    type_prohibited = {
+        "object": ["patternProperties", "minProperties"],
+        "array": ["minItems", "maxItems", "uniqueItems"],
+        "string": ["pattern", "format", "minLength", "maxLength"],
+        "number": ["minimum", "maximum", "multipleOf"],
+        "integer": ["exclusiveMinimum", "exclusiveMaximum"],
+    }
+
+    schema_type = schema.get("type")
+    if schema_type in type_prohibited:
+        prohibited = set(type_prohibited[schema_type])
+        used_prohibited = prohibited.intersection(schema.keys())
+        if used_prohibited:
+            raise SchemaValidationError(
+                f"Schema uses prohibited keywords for type '{schema_type}'",
+                context={
+                    "path": current_path,
+                    "type": schema_type,
+                    "prohibited_used": list(used_prohibited),
+                    "tips": [
+                        f"Remove these prohibited keywords: {list(used_prohibited)}",
+                        "OpenAI structured output has limited keyword support",
+                        "Use only basic type constraints",
+                    ],
+                },
+            )

ostruct/cli/security/allowed_checker.py

@@ -25,6 +25,9 @@ def is_path_in_allowed_dirs(
     Returns:
         True if path is within one of the allowed directories; False otherwise.
 
+    Raises:
+        TypeError: If path is None or not a string/Path object.
+
     Example:
         >>> allowed = [Path("/base"), Path("/tmp")]
         >>> is_path_in_allowed_dirs("/base/file.txt", allowed)
@@ -32,6 +35,11 @@ def is_path_in_allowed_dirs(
         >>> is_path_in_allowed_dirs("/etc/passwd", allowed)
         False
     """
+    if path is None:
+        raise TypeError("path must be a string or Path object")
+    if not isinstance(path, (str, Path)):
+        raise TypeError("path must be a string or Path object")
+
     norm_path = normalize_path(path)
     norm_allowed = [normalize_path(d) for d in allowed_dirs]
 

ostruct/cli/security/base.py

@@ -0,0 +1,46 @@
+"""Base class for security-related errors."""
+
+from typing import Any, Dict, Optional
+
+from ostruct.cli.base_errors import CLIError
+from ostruct.cli.exit_codes import ExitCode
+
+
+class SecurityErrorBase(CLIError):
+    """Base class for security-related errors."""
+
+    def __init__(
+        self,
+        message: str,
+        context: Optional[Dict[str, Any]] = None,
+        details: Optional[str] = None,
+        has_been_logged: bool = False,
+    ) -> None:
+        """Initialize security error.
+
+        Args:
+            message: The error message.
+            context: Additional context for the error.
+            details: Detailed explanation of the error.
+            has_been_logged: Whether the error has been logged.
+        """
+        if context is None:
+            context = {}
+        context["category"] = "security"
+        super().__init__(
+            message,
+            context=context,
+            exit_code=ExitCode.SECURITY_ERROR,
+            details=details,
+        )
+        self._has_been_logged = has_been_logged
+
+    @property
+    def has_been_logged(self) -> bool:
+        """Whether this error has been logged."""
+        return self._has_been_logged
+
+    @has_been_logged.setter
+    def has_been_logged(self, value: bool) -> None:
+        """Set whether this error has been logged."""
+        self._has_been_logged = value