mcp-souschef 2.0.1__py3-none-any.whl → 2.2.0__py3-none-any.whl

souschef/filesystem/__init__.py

@@ -0,0 +1,5 @@
+"""Filesystem operations."""
+
+from souschef.filesystem.operations import list_directory, read_file
+
+__all__ = ["list_directory", "read_file"]

souschef/filesystem/operations.py

@@ -0,0 +1,67 @@
+"""Filesystem operations for Chef cookbook exploration."""
+
+from mcp.server.fastmcp import FastMCP
+
+from souschef.core.constants import (
+    ERROR_FILE_NOT_FOUND,
+    ERROR_IS_DIRECTORY,
+    ERROR_PERMISSION_DENIED,
+)
+from souschef.core.path_utils import _normalize_path
+
+# Get MCP instance to register tools
+mcp = FastMCP("souschef")
+
+
+@mcp.tool()
+def list_directory(path: str) -> list[str] | str:
+    """
+    List the contents of a directory.
+
+    Args:
+        path: The path to the directory to list.
+
+    Returns:
+        A list of filenames in the directory, or an error message.
+
+    """
+    try:
+        dir_path = _normalize_path(path)
+        return [item.name for item in dir_path.iterdir()]
+    except ValueError as e:
+        return f"Error: {e}"
+    except FileNotFoundError:
+        return f"Error: Directory not found at {path}"
+    except NotADirectoryError:
+        return f"Error: {path} is not a directory"
+    except PermissionError:
+        return ERROR_PERMISSION_DENIED.format(path=path)
+    except Exception as e:
+        return f"An error occurred: {e}"
+
+
+@mcp.tool()
+def read_file(path: str) -> str:
+    """
+    Read the contents of a file.
+
+    Args:
+        path: The path to the file to read.
+
+    Returns:
+        The contents of the file, or an error message.
+
+    """
+    try:
+        file_path = _normalize_path(path)
+        return file_path.read_text(encoding="utf-8")
+    except ValueError as e:
+        return f"Error: {e}"
+    except FileNotFoundError:
+        return ERROR_FILE_NOT_FOUND.format(path=path)
+    except IsADirectoryError:
+        return ERROR_IS_DIRECTORY.format(path=path)
+    except PermissionError:
+        return ERROR_PERMISSION_DENIED.format(path=path)
+    except Exception as e:
+        return f"An error occurred: {e}"

souschef/parsers/__init__.py

@@ -0,0 +1,36 @@
+"""Chef cookbook parsers."""
+
+from souschef.core.validation import (
+    ValidationCategory,
+    ValidationEngine,
+    ValidationLevel,
+    ValidationResult,
+)
+from souschef.parsers.attributes import parse_attributes
+from souschef.parsers.habitat import parse_habitat_plan
+from souschef.parsers.inspec import (
+    convert_inspec_to_test,
+    generate_inspec_from_chef,
+    parse_inspec_profile,
+)
+from souschef.parsers.metadata import list_cookbook_structure, read_cookbook_metadata
+from souschef.parsers.recipe import parse_recipe
+from souschef.parsers.resource import parse_custom_resource
+from souschef.parsers.template import parse_template
+
+__all__ = [
+    "parse_template",
+    "parse_recipe",
+    "parse_attributes",
+    "parse_custom_resource",
+    "read_cookbook_metadata",
+    "list_cookbook_structure",
+    "parse_inspec_profile",
+    "convert_inspec_to_test",
+    "generate_inspec_from_chef",
+    "parse_habitat_plan",
+    "ValidationCategory",
+    "ValidationEngine",
+    "ValidationLevel",
+    "ValidationResult",
+]

souschef/parsers/attributes.py

@@ -0,0 +1,257 @@
+"""Chef attributes file parser."""
+
+import re
+from typing import Any
+
+from souschef.core.constants import (
+    ERROR_FILE_NOT_FOUND,
+    ERROR_IS_DIRECTORY,
+    ERROR_PERMISSION_DENIED,
+)
+from souschef.core.path_utils import _normalize_path
+from souschef.parsers.template import _strip_ruby_comments
+
+
+def parse_attributes(path: str, resolve_precedence: bool = True) -> str:
+    """
+    Parse a Chef attributes file and extract attribute definitions.
+
+    Analyzes attributes file and extracts all attribute definitions with their
+    precedence levels and values. By default, resolves precedence conflicts
+    to show the winning value for each attribute path.
+
+    Chef attribute precedence (lowest to highest):
+    1. default - Normal default value
+    2. force_default - Forced default, higher than regular default
+    3. normal - Normal attribute set by cookbook
+    4. override - Override values
+    5. force_override - Forced override, cannot be overridden
+    6. automatic - Automatically detected by Ohai (highest precedence)
+
+    Args:
+        path: Path to the attributes (.rb) file.
+        resolve_precedence: If True (default), resolves precedence conflicts
+            and shows only winning values. If False, shows all attributes.
+
+    Returns:
+        Formatted string with extracted attributes.
+
+    """
+    try:
+        file_path = _normalize_path(path)
+        content = file_path.read_text(encoding="utf-8")
+
+        attributes = _extract_attributes(content)
+
+        if not attributes:
+            return f"Warning: No attributes found in {path}"
+
+        if resolve_precedence:
+            resolved = _resolve_attribute_precedence(attributes)
+            return _format_resolved_attributes(resolved)
+        else:
+            return _format_attributes(attributes)
+
+    except ValueError as e:
+        return f"Error: {e}"
+    except FileNotFoundError:
+        return ERROR_FILE_NOT_FOUND.format(path=path)
+    except IsADirectoryError:
+        return ERROR_IS_DIRECTORY.format(path=path)
+    except PermissionError:
+        return ERROR_PERMISSION_DENIED.format(path=path)
+    except Exception as e:
+        return f"An error occurred: {e}"
+
+
+def _extract_attributes(content: str) -> list[dict[str, str]]:
+    """
+    Extract Chef attributes from attributes file content.
+
+    Args:
+        content: Raw content of attributes file.
+
+    Returns:
+        List of dictionaries containing attribute information.
+
+    """
+    attributes = []
+    # Strip comments first
+    clean_content = _strip_ruby_comments(content)
+
+    # Match attribute declarations with all precedence levels
+    # Chef precedence levels (lowest to highest):
+    # default < force_default < normal < override < force_override < automatic
+    pattern = (
+        r"(default|force_default|normal|override|force_override|automatic)"
+        r"((?:\[[^\]]+\])+)\s*=\s*([^\n]+)"
+    )
+
+    for match in re.finditer(pattern, clean_content, re.DOTALL):
+        precedence = match.group(1)
+        # Extract the bracket part and clean it up
+        brackets = match.group(2)
+        # Clean up the path - remove quotes and brackets, convert to dot notation
+        attr_path = (
+            brackets.replace("']['", ".")
+            .replace('"]["', ".")
+            .replace("['", "")
+            .replace("']", "")
+            .replace('["', "")
+            .replace('"]', "")
+        )
+        value = match.group(3).strip()
+
+        attributes.append(
+            {
+                "precedence": precedence,
+                "path": attr_path,
+                "value": value,
+            }
+        )
+
+    return attributes
+
+
+def _get_precedence_level(precedence: str) -> int:
+    """
+    Get numeric precedence level for Chef attribute precedence.
+
+    Chef attribute precedence (lowest to highest):
+    1. default
+    2. force_default
+    3. normal
+    4. override
+    5. force_override
+    6. automatic
+
+    Args:
+        precedence: Chef attribute precedence level.
+
+    Returns:
+        Numeric precedence level (1-6).
+
+    """
+    precedence_map = {
+        "default": 1,
+        "force_default": 2,
+        "normal": 3,
+        "override": 4,
+        "force_override": 5,
+        "automatic": 6,
+    }
+    return precedence_map.get(precedence, 1)
+
+
+def _resolve_attribute_precedence(
+    attributes: list[dict[str, str]],
+) -> dict[str, dict[str, str | bool | int]]:
+    """
+    Resolve attribute precedence conflicts based on Chef's precedence rules.
+
+    When multiple attributes with the same path exist, the one with
+    higher precedence wins. Returns the winning value for each path
+    along with precedence information.
+
+    Args:
+        attributes: List of attribute dictionaries with precedence, path, and value.
+
+    Returns:
+        Dictionary mapping attribute paths to their resolved values and metadata.
+
+    """
+    # Group attributes by path
+    path_groups: dict[str, list[dict[str, str]]] = {}
+    for attr in attributes:
+        path = attr["path"]
+        if path not in path_groups:
+            path_groups[path] = []
+        path_groups[path].append(attr)
+
+    # Resolve precedence for each path
+    resolved: dict[str, dict[str, Any]] = {}
+    for path, attrs in path_groups.items():
+        # Find attribute with highest precedence
+        winning_attr = max(attrs, key=lambda a: _get_precedence_level(a["precedence"]))
+
+        # Check for conflicts (multiple values at different precedence levels)
+        has_conflict = len(attrs) > 1
+        conflict_info = []
+        if has_conflict:
+            # Sort by precedence for conflict reporting
+            sorted_attrs = sorted(
+                attrs, key=lambda a: _get_precedence_level(a["precedence"])
+            )
+            conflict_info = [
+                f"{a['precedence']}={a['value']}" for a in sorted_attrs[:-1]
+            ]
+
+        resolved[path] = {
+            "value": winning_attr["value"],
+            "precedence": winning_attr["precedence"],
+            "precedence_level": _get_precedence_level(winning_attr["precedence"]),
+            "has_conflict": has_conflict,
+            "overridden_values": ", ".join(conflict_info) if conflict_info else "",
+        }
+
+    return resolved
+
+
+def _format_attributes(attributes: list[dict[str, str]]) -> str:
+    """
+    Format attributes list as a readable string.
+
+    Args:
+        attributes: List of attribute dictionaries.
+
+    Returns:
+        Formatted string representation.
+
+    """
+    result = []
+    for attr in attributes:
+        result.append(f"{attr['precedence']}[{attr['path']}] = {attr['value']}")
+
+    return "\n".join(result)
+
+
+def _format_resolved_attributes(
+    resolved: dict[str, dict[str, str | bool | int]],
+) -> str:
+    """
+    Format resolved attributes with precedence information.
+
+    Args:
+        resolved: Dictionary mapping attribute paths to resolved values and metadata.
+
+    Returns:
+        Formatted string showing resolved attributes with precedence details.
+
+    """
+    if not resolved:
+        return "No attributes found."
+
+    result = ["Resolved Attributes (with precedence):", "=" * 50, ""]
+
+    # Sort by attribute path for consistent output
+    for path in sorted(resolved.keys()):
+        info = resolved[path]
+        result.append(f"Attribute: {path}")
+        result.append(f"  Value: {info['value']}")
+        result.append(
+            f"  Precedence: {info['precedence']} (level {info['precedence_level']})"
+        )
+
+        if info["has_conflict"]:
+            result.append(f"  ⚠️  Overridden values: {info['overridden_values']}")
+
+        result.append("")  # Blank line between attributes
+
+    # Add summary
+    conflict_count = sum(1 for info in resolved.values() if info["has_conflict"])
+    result.append("=" * 50)
+    result.append(f"Total attributes: {len(resolved)}")
+    if conflict_count > 0:
+        result.append(f"Attributes with precedence conflicts: {conflict_count}")
+
+    return "\n".join(result)

souschef/parsers/habitat.py

@@ -0,0 +1,317 @@
+"""Chef Habitat plan parser."""
+
+import json
+import re
+from typing import Any
+
+from souschef.core.constants import (
+    ERROR_FILE_NOT_FOUND,
+    ERROR_IS_DIRECTORY,
+    ERROR_PERMISSION_DENIED,
+)
+from souschef.core.path_utils import _normalize_path
+
+# Maximum length for variable values in Habitat plan parsing
+# Prevents ReDoS attacks from extremely long variable assignments
+MAX_PLAN_VALUE_LENGTH = 10000
+
+
+def parse_habitat_plan(plan_path: str) -> str:
+    """
+    Parse a Chef Habitat plan file (plan.sh) and extract package metadata.
+
+    Analyzes Habitat plans to extract package information, dependencies,
+    ports, services, and build callbacks for container conversion.
+
+    Args:
+        plan_path: Path to the plan.sh file
+
+    Returns:
+        JSON string with parsed plan metadata
+
+    """
+    try:
+        normalized_path = _normalize_path(plan_path)
+        if not normalized_path.exists():
+            return ERROR_FILE_NOT_FOUND.format(path=normalized_path)
+        if normalized_path.is_dir():
+            return ERROR_IS_DIRECTORY.format(path=normalized_path)
+
+        content = normalized_path.read_text(encoding="utf-8")
+        metadata: dict[str, Any] = {
+            "package": {},
+            "dependencies": {"build": [], "runtime": []},
+            "ports": [],
+            "binds": [],
+            "service": {},
+            "callbacks": {},
+        }
+
+        # Extract package info
+        metadata["package"]["name"] = _extract_plan_var(content, "pkg_name")
+        metadata["package"]["origin"] = _extract_plan_var(content, "pkg_origin")
+        metadata["package"]["version"] = _extract_plan_var(content, "pkg_version")
+        metadata["package"]["maintainer"] = _extract_plan_var(content, "pkg_maintainer")
+        metadata["package"]["license"] = _extract_plan_array(content, "pkg_license")
+        metadata["package"]["description"] = _extract_plan_var(
+            content, "pkg_description"
+        )
+        metadata["package"]["upstream_url"] = _extract_plan_var(
+            content, "pkg_upstream_url"
+        )
+        metadata["package"]["source"] = _extract_plan_var(content, "pkg_source")
+
+        # Extract dependencies
+        metadata["dependencies"]["build"] = _extract_plan_array(
+            content, "pkg_build_deps"
+        )
+        metadata["dependencies"]["runtime"] = _extract_plan_array(content, "pkg_deps")
+
+        # Extract ports and bindings
+        metadata["ports"] = _extract_plan_exports(content, "pkg_exports")
+        metadata["binds"] = _extract_plan_exports(content, "pkg_binds_optional")
+
+        # Extract service config
+        metadata["service"]["run"] = _extract_plan_var(content, "pkg_svc_run")
+        metadata["service"]["user"] = _extract_plan_var(content, "pkg_svc_user")
+        metadata["service"]["group"] = _extract_plan_var(content, "pkg_svc_group")
+
+        # Extract callbacks
+        for callback in ["do_build", "do_install", "do_init", "do_setup_environment"]:
+            callback_content = _extract_plan_function(content, callback)
+            if callback_content:
+                metadata["callbacks"][callback] = callback_content
+
+        return json.dumps(metadata, indent=2)
+    except PermissionError:
+        return ERROR_PERMISSION_DENIED.format(path=plan_path)
+    except Exception as e:
+        return f"Error parsing Habitat plan: {e}"
+
+
+def _extract_plan_var(content: str, var_name: str) -> str:
+    """
+    Extract a variable value from a Habitat plan.
+
+    This helper supports both quoted and unquoted assignments and allows
+    escaped quotes within quoted values. If the variable is not found,
+    an empty string is returned.
+
+    Args:
+        content: Full text of the Habitat plan.
+        var_name: Name of the variable to extract.
+
+    Returns:
+        The extracted variable value, or an empty string if not present.
+
+    """
+    # First, try to match a quoted value (single or double quotes), allowing
+    # escaped characters (e.g. \" or \') inside the value. We anchor at the
+    # start of the line to avoid partial matches elsewhere.
+    # Use a bounded, non-greedy quantifier to prevent ReDoS on malformed input.
+    quoted_pattern = (
+        rf'^{re.escape(var_name)}=(["\'])'
+        rf"(?P<value>(?:\\.|(?!\1).){{0,{MAX_PLAN_VALUE_LENGTH}}}?)\1"
+    )
+    match = re.search(quoted_pattern, content, re.MULTILINE | re.DOTALL)
+    if match:
+        return match.group("value").strip()
+
+    # Fallback: match an unquoted value up to the end of the line or a comment.
+    unquoted_pattern = rf"^{re.escape(var_name)}=([^\n#]+)"
+    match = re.search(unquoted_pattern, content, re.MULTILINE)
+    return match.group(1).strip() if match else ""
+
+
+def _extract_plan_array(content: str, var_name: str) -> list[str]:
+    """Extract an array variable from a Habitat plan."""
+    # Find the start of the array declaration
+    pattern = rf"{var_name}=\("
+    match = re.search(pattern, content)
+    if not match:
+        return []
+
+    # Manually parse to handle nested parentheses correctly
+    start_pos = match.end()
+    paren_count = 1
+    end_pos = start_pos
+
+    # Find the matching closing parenthesis
+    while end_pos < len(content) and paren_count > 0:
+        if content[end_pos] == "(":
+            paren_count += 1
+        elif content[end_pos] == ")":
+            paren_count -= 1
+        end_pos += 1
+
+    if paren_count != 0:
+        # Unmatched parentheses
+        return []
+
+    # Extract the content between parentheses (excluding the final closing paren)
+    array_content = content[start_pos : end_pos - 1]
+
+    # Split by newlines and process each line
+    elements = []
+    for line in array_content.strip().split("\n"):
+        # Remove inline comments
+        line = line.split("#")[0].strip()
+        if not line:
+            continue
+
+        # Remove quotes and whitespace
+        line = line.strip("\"'").strip()
+        if line:
+            elements.append(line)
+
+    return elements
+
+
+def _extract_plan_exports(content: str, var_name: str) -> list[dict[str, str]]:
+    """Extract port exports or bindings from a Habitat plan."""
+    # Find the start of the array declaration
+    pattern = rf"{var_name}=\("
+    match = re.search(pattern, content)
+    if not match:
+        return []
+
+    # Manually parse to handle nested parentheses correctly
+    start_pos = match.end()
+    paren_count = 1
+    end_pos = start_pos
+
+    # Find the matching closing parenthesis
+    while end_pos < len(content) and paren_count > 0:
+        if content[end_pos] == "(":
+            paren_count += 1
+        elif content[end_pos] == ")":
+            paren_count -= 1
+        end_pos += 1
+
+    if paren_count != 0:
+        # Unmatched parentheses
+        return []
+
+    # Extract the content between parentheses (excluding the final closing paren)
+    exports_content = content[start_pos : end_pos - 1]
+
+    exports = []
+    for line in exports_content.strip().split("\n"):
+        export_match = re.search(r"\[([^\]]+)\]=([^\s]+)", line)
+        if export_match:
+            exports.append(
+                {"name": export_match.group(1), "value": export_match.group(2)}
+            )
+    return exports
+
+
+def _is_quote_blocked(
+    ch: str, in_single_quote: bool, in_double_quote: bool, in_backtick: bool
+) -> bool:
+    """Check if a quote character is blocked by other active quotes."""
+    if ch == "'":
+        return in_double_quote or in_backtick
+    if ch == '"':
+        return in_single_quote or in_backtick
+    if ch == "`":
+        return in_single_quote or in_double_quote
+    return False
+
+
+def _toggle_quote(
+    ch: str, in_single_quote: bool, in_double_quote: bool, in_backtick: bool
+) -> tuple[bool, bool, bool]:
+    """Toggle the appropriate quote state based on character."""
+    if ch == "'":
+        return not in_single_quote, in_double_quote, in_backtick
+    if ch == '"':
+        return in_single_quote, not in_double_quote, in_backtick
+    if ch == "`":
+        return in_single_quote, in_double_quote, not in_backtick
+    return in_single_quote, in_double_quote, in_backtick
+
+
+def _update_quote_state(
+    ch: str,
+    in_single_quote: bool,
+    in_double_quote: bool,
+    in_backtick: bool,
+    escape_next: bool,
+) -> tuple[bool, bool, bool, bool]:
+    """Update quote tracking state for shell script parsing."""
+    # Handle escape sequences
+    if escape_next:
+        return in_single_quote, in_double_quote, in_backtick, False
+
+    if ch == "\\":
+        return in_single_quote, in_double_quote, in_backtick, True
+
+    # Handle quote characters
+    if ch in ("'", '"', "`") and not _is_quote_blocked(
+        ch, in_single_quote, in_double_quote, in_backtick
+    ):
+        single, double, backtick = _toggle_quote(
+            ch, in_single_quote, in_double_quote, in_backtick
+        )
+        return single, double, backtick, False
+
+    return in_single_quote, in_double_quote, in_backtick, False
+
+
+def _extract_plan_function(content: str, func_name: str) -> str:
+    """
+    Extract a shell function body from a Habitat plan.
+
+    Uses brace counting to handle nested braces in conditionals and loops.
+
+    Args:
+        content: Full text of the Habitat plan.
+        func_name: Name of the function to extract.
+
+    Returns:
+        The function body as a string, or an empty string if the function
+        is not found or is malformed.
+
+    """
+    # Find the start of the function definition: func_name() {
+    func_def_pattern = rf"{re.escape(func_name)}\s*\(\)\s*{{"
+    match = re.search(func_def_pattern, content)
+    if not match:
+        return ""
+
+    start_index = match.end()
+    brace_count = 1
+    i = start_index
+
+    in_single_quote = False
+    in_double_quote = False
+    in_backtick = False
+    escape_next = False
+
+    while i < len(content):
+        ch = content[i]
+
+        # Update quote/escape state
+        (
+            in_single_quote,
+            in_double_quote,
+            in_backtick,
+            escape_next,
+        ) = _update_quote_state(
+            ch, in_single_quote, in_double_quote, in_backtick, escape_next
+        )
+
+        # Count braces only when not inside quotes
+        if not (in_single_quote or in_double_quote or in_backtick):
+            if ch == "{":
+                brace_count += 1
+            elif ch == "}":
+                brace_count -= 1
+                if brace_count == 0:
+                    body = content[start_index:i]
+                    return body.strip("\n").strip()
+
+        i += 1
+
+    # Unbalanced braces or malformed definition
+    return ""