litestar-vite 0.1.1__py3-none-any.whl → 0.15.0__py3-none-any.whl

litestar_vite/codegen/_ts.py

@@ -0,0 +1,235 @@
+"""TypeScript conversion helpers for code generation."""
+
+import re
+from pathlib import PurePosixPath
+from typing import Any, cast
+
+_PATH_PARAM_TYPE_PATTERN = re.compile(r"\{([^:}]+):[^}]+\}")
+
+_OPENAPI_STRING_FORMAT_TO_TS_ALIAS: dict[str, str] = {
+    "uuid": "UUID",
+    "date-time": "DateTime",
+    "date": "DateOnly",
+    "time": "TimeOnly",
+    "duration": "Duration",
+    "email": "Email",
+    "idn-email": "Email",
+    "uri": "URI",
+    "url": "URI",
+    "iri": "URI",
+    "iri-reference": "URI",
+    "uri-reference": "URI",
+    "uri-template": "URI",
+    "ipv4": "IPv4",
+    "ipv6": "IPv6",
+}
+
+
+def normalize_path(path: str) -> str:
+    """Normalize route path to use {param} syntax.
+
+    Returns:
+        Normalized path string.
+    """
+    if not path or path == "/":
+        return path
+    return _PATH_PARAM_TYPE_PATTERN.sub(r"{\1}", str(PurePosixPath(path)))
+
+
+def ts_type_from_openapi(schema_dict: dict[str, Any]) -> str:
+    """Convert an OpenAPI schema dict to a TypeScript type string.
+
+    This function is intentionally lightweight and mirrors the historical
+    behavior used in this project's unit tests (OpenAPI 3.1 union types,
+    oneOf nullable patterns, etc.). It is not a full OpenAPI-to-TypeScript
+    compiler.
+
+    Returns:
+        A TypeScript type expression string.
+    """
+    if not schema_dict:
+        return "any"
+
+    ref = schema_dict.get("$ref")
+    if isinstance(ref, str) and ref:
+        return ref.split("/")[-1]
+
+    if "anyOf" in schema_dict and isinstance(schema_dict["anyOf"], list) and schema_dict["anyOf"]:
+        schemas = cast("list[Any]", schema_dict["anyOf"])
+        union = {ts_type_from_subschema(s) for s in schemas}
+        return join_union(union)
+
+    result = "any"
+    match schema_dict:
+        case {"const": const} if const is not None:
+            result = "any" if const is False else ts_literal(const)
+        case {"enum": enum} if isinstance(enum, list) and enum:
+            enum_values = cast("list[Any]", enum)
+            result = " | ".join(ts_literal(v) for v in enum_values)
+        case {"oneOf": one_of} if isinstance(one_of, list) and one_of:
+            schemas = cast("list[Any]", one_of)
+            union = {ts_type_from_subschema(s) for s in schemas}
+            result = join_union(union)
+        case {"allOf": all_of} if isinstance(all_of, list) and all_of:
+            schemas = cast("list[Any]", all_of)
+            parts = [wrap_union_for_intersection(ts_type_from_subschema(s)) for s in schemas]
+            parts = [p for p in parts if p and p != "any"]
+            result = " & ".join(parts) if parts else "any"
+        case {"type": list()}:
+            type_entries_list: list[Any] = schema_dict["type"]
+            parts = [ts_type_from_openapi_type_entry(t, schema_dict) for t in type_entries_list if isinstance(t, str)]
+            result = join_union(set(parts)) if parts else "any"
+        case {"type": str() as schema_type}:
+            result = ts_type_from_openapi_type_entry(schema_type, schema_dict)
+        case _:
+            pass
+
+    return result
+
+
+def python_type_to_typescript(py_type: str, *, fallback: str = "unknown") -> tuple[str, bool]:
+    """Convert a Python typing string representation into a TS type and optionality flag.
+
+    Returns:
+        A tuple of the TypeScript type string and a boolean indicating if the type is optional.
+    """
+    if not py_type:
+        return fallback, False
+
+    normalized = py_type.replace("typing.", "").replace("types.", "")
+    optional = "None" in normalized or "NoneType" in normalized or "Optional[" in normalized
+
+    normalized = normalized.replace("NoneType", "None").replace("None", "null")
+
+    mapping: dict[str, str] = {
+        "str": "string",
+        "int": "number",
+        "float": "number",
+        "bool": "boolean",
+        "dict": "Record<string, unknown>",
+        "Dict": "Record<string, unknown>",
+        "list": f"{fallback}[]",
+        "List": f"{fallback}[]",
+        "tuple": f"{fallback}[]",
+        "Tuple": f"{fallback}[]",
+        "set": f"{fallback}[]",
+        "Set": f"{fallback}[]",
+        "Any": fallback,
+        "unknown": "unknown",
+        "null": "null",
+    }
+
+    for k, v in mapping.items():
+        if normalized == k:
+            return v, optional
+
+    return normalized, optional
+
+
+def collect_ref_names(schema_dict: Any) -> set[str]:
+    """Collect referenced component names from an OpenAPI schema dict.
+
+    Returns:
+        A set of referenced component names.
+    """
+    refs: set[str] = set()
+    if isinstance(schema_dict, dict):
+        schema_dict_t = cast("dict[str, Any]", schema_dict)
+        ref_any = schema_dict_t.get("$ref")
+        if isinstance(ref_any, str) and ref_any.startswith("#/components/schemas/"):
+            refs.add(ref_any.split("/")[-1])
+        for v in schema_dict_t.values():
+            refs.update(collect_ref_names(v))
+    elif isinstance(schema_dict, list):
+        for item in cast("list[Any]", schema_dict):
+            refs.update(collect_ref_names(item))
+    return refs
+
+
+def ts_type_from_subschema(schema: Any) -> str:
+    if isinstance(schema, dict):
+        return ts_type_from_openapi(cast("dict[str, Any]", schema))
+    return "any"
+
+
+def ts_type_from_openapi_type_entry(type_name: str, schema_dict: dict[str, Any]) -> str:
+    primitive_types: dict[str, str] = {
+        "string": "string",
+        "integer": "number",
+        "number": "number",
+        "boolean": "boolean",
+        "null": "null",
+    }
+
+    result = primitive_types.get(type_name, "any")
+    if type_name == "string":
+        fmt = schema_dict.get("format")
+        if isinstance(fmt, str) and fmt:
+            result = _OPENAPI_STRING_FORMAT_TO_TS_ALIAS.get(fmt, result)
+    if type_name == "array":
+        items = schema_dict.get("items")
+        item_type = ts_type_from_subschema(items) if isinstance(items, dict) else "unknown"
+        result = f"{wrap_for_array(item_type)}[]"
+    elif type_name == "object":
+        properties = schema_dict.get("properties")
+        if not isinstance(properties, dict) or not properties:
+            result = "{}"
+        else:
+            required_list = schema_dict.get("required")
+            required: set[str] = set()
+            if isinstance(required_list, list):
+                required = {v for v in cast("list[Any]", required_list) if isinstance(v, str)}
+
+            lines: list[str] = ["{"]
+            for name, prop_schema in cast("dict[str, Any]", properties).items():
+                ts_type = ts_type_from_subschema(prop_schema)
+                optional = "" if name in required else "?"
+                lines.append(f"  {name}{optional}: {ts_type};")
+            lines.append("}")
+            result = "\n".join(lines)
+
+    return result
+
+
+def wrap_for_array(type_expr: str) -> str:
+    expr = type_expr.strip()
+    if not expr:
+        return "unknown"
+    if expr.startswith("(") and expr.endswith(")"):
+        return expr
+    # Parenthesize unions/intersections so `(A | B)[]` / `(A & B)[]` is emitted correctly.
+    if " | " in expr or (" & " in expr and not expr.startswith("{")):
+        return f"({expr})"
+    return expr
+
+
+def wrap_union_for_intersection(type_expr: str) -> str:
+    expr = type_expr.strip()
+    if not expr:
+        return "any"
+    if expr.startswith("(") and expr.endswith(")"):
+        return expr
+    if " | " in expr:
+        return f"({expr})"
+    return expr
+
+
+def join_union(types: set[str]) -> str:
+    if not types:
+        return "any"
+    if len(types) == 1:
+        return next(iter(types))
+    return " | ".join(sorted(types))
+
+
+def ts_literal(value: Any) -> str:
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int | float):
+        return str(value)
+    if isinstance(value, str):
+        escaped = value.replace("\\\\", "\\\\\\\\").replace('"', '\\"')
+        return f'"{escaped}"'
+    return "any"

litestar_vite/codegen/_utils.py

@@ -0,0 +1,141 @@
+"""Utilities for deterministic code generation and file output."""
+
+import hashlib
+import json
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+
+def deep_sort_dict(obj: Any) -> Any:
+    """Recursively sort all dictionary keys for deterministic JSON output.
+
+    Args:
+        obj: Any Python object (dict, list, or primitive).
+
+    Returns:
+        The object with all nested dict keys sorted.
+    """
+    if isinstance(obj, dict):
+        # pyright: ignore - intentionally working with Any types for generic dict sorting
+        return {k: deep_sort_dict(v) for k, v in sorted(obj.items())}  # pyright: ignore[reportUnknownVariableType,reportUnknownArgumentType]
+    if isinstance(obj, list):
+        return [deep_sort_dict(item) for item in obj]  # pyright: ignore[reportUnknownVariableType]
+    return obj
+
+
+def strip_timestamp_for_comparison(content: bytes) -> bytes:
+    """Remove generatedAt and other timestamp fields for content comparison.
+
+    This allows comparing file content while ignoring fields that change
+    on every generation (like timestamps).
+
+    Args:
+        content: JSON content as bytes.
+
+    Returns:
+        JSON content with timestamp fields removed, sorted keys.
+    """
+    try:
+        data = json.loads(content)
+        # Remove fields that change on every generation
+        data.pop("generatedAt", None)
+        # Return sorted JSON for consistent comparison
+        return json.dumps(data, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    except (json.JSONDecodeError, TypeError, AttributeError):
+        # If we can't parse the content, return as-is
+        return content
+
+
+def write_if_changed(
+    path: Path,
+    content: bytes | str,
+    *,
+    normalize_for_comparison: Callable[[bytes], bytes] | None = None,
+    encoding: str = "utf-8",
+) -> bool:
+    """Write content to file only if it differs from the existing content.
+
+    Uses hash comparison to avoid unnecessary writes that would trigger
+    file watchers and unnecessary rebuilds. Optionally normalizes content
+    before comparison (e.g., to strip timestamps).
+
+    Args:
+        path: The file path to write to.
+        content: The content to write (bytes or str).
+        normalize_for_comparison: Optional callback to normalize content before
+            comparison (e.g., strip timestamps). The file is written with the
+            original content, not the normalized version.
+        encoding: Encoding for string content.
+
+    Returns:
+        True if file was written (content changed), False if skipped (unchanged).
+    """
+    # Ensure trailing newline for POSIX compliance
+    if isinstance(content, str):
+        if not content.endswith("\n"):
+            content += "\n"
+        content_bytes = content.encode(encoding)
+    else:
+        if not content.endswith(b"\n"):
+            content += b"\n"
+        content_bytes = content
+
+    if path.exists():
+        try:
+            existing = path.read_bytes()
+
+            # Normalize both for comparison if a normalizer is provided
+            if normalize_for_comparison:
+                existing_normalized = normalize_for_comparison(existing)
+                new_normalized = normalize_for_comparison(content_bytes)
+            else:
+                existing_normalized = existing
+                new_normalized = content_bytes
+
+            # Compare using MD5 hash for efficiency
+            existing_hash = hashlib.md5(existing_normalized).hexdigest()  # noqa: S324
+            new_hash = hashlib.md5(new_normalized).hexdigest()  # noqa: S324
+            if existing_hash == new_hash:
+                return False
+        except OSError:
+            pass
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if isinstance(content, str):
+        path.write_text(content, encoding=encoding)
+    else:
+        path.write_bytes(content)
+    return True
+
+
+def encode_deterministic_json(
+    data: dict[str, Any], *, indent: int = 2, serializer: Callable[[Any], bytes] | None = None
+) -> bytes:
+    """Encode JSON with sorted keys for deterministic output.
+
+    This is a wrapper that ensures all nested dict keys are sorted
+    before serialization, producing byte-identical output for the
+    same input data regardless of insertion order.
+
+    Args:
+        data: Dictionary to encode.
+        indent: Indentation level for formatting.
+        serializer: Optional custom serializer function. If not provided,
+            uses litestar's default encode_json.
+
+    Returns:
+        Formatted JSON bytes with sorted keys.
+    """
+    import msgspec
+    from litestar.serialization import encode_json
+
+    sorted_data = deep_sort_dict(data)
+    if serializer is not None:
+        content = msgspec.json.format(serializer(sorted_data), indent=indent)
+    else:
+        content = msgspec.json.format(encode_json(sorted_data), indent=indent)
+    # Ensure trailing newline for POSIX compliance
+    if not content.endswith(b"\n"):
+        content += b"\n"
+    return content

litestar_vite/commands.py

@@ -0,0 +1,73 @@
+"""Vite commands module.
+
+This module provides utility functions for Vite project initialization.
+The main scaffolding functionality has moved to litestar_vite.scaffolding.
+"""
+
+from typing import TYPE_CHECKING
+
+from litestar_vite.config import JINJA_INSTALLED
+from litestar_vite.exceptions import MissingDependencyError
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+def init_vite(
+    root_path: "Path",
+    resource_path: "Path",
+    asset_url: "str",
+    static_path: "Path",
+    bundle_path: "Path",
+    enable_ssr: "bool",
+    vite_port: int,
+    litestar_port: int,
+    framework: str = "react",
+) -> None:
+    """Initialize a new Vite project using the scaffolding system.
+
+    Args:
+        root_path: Root directory for the Vite project.
+        resource_path: Directory containing source files.
+        asset_url: Base URL for serving assets.
+        static_path: Directory for static (unprocessed) frontend assets.
+        bundle_path: Output directory for built files.
+        enable_ssr: Enable server-side rendering.
+        vite_port: Port for Vite dev server.
+        litestar_port: Port for Litestar server.
+        framework: Framework template to use (default: react).
+
+    Raises:
+        MissingDependencyError: If Jinja2 is not installed.
+        ValueError: If the specified framework template is not found.
+    """
+    if not JINJA_INSTALLED:
+        raise MissingDependencyError(package="jinja2", install_package="jinja")
+
+    from litestar_vite.scaffolding import TemplateContext, generate_project
+    from litestar_vite.scaffolding.templates import FrameworkType, get_template
+
+    template = get_template(framework)
+    if template is None:
+        template = get_template(FrameworkType.REACT)
+    if template is None:  # pragma: no cover
+        msg = f"Could not find template for framework: {framework}"
+        raise ValueError(msg)
+
+    context = TemplateContext(
+        project_name=root_path.name or "my-project",
+        framework=template,
+        use_typescript=template.uses_typescript,
+        use_tailwind=False,
+        vite_port=vite_port,
+        litestar_port=litestar_port,
+        asset_url=asset_url,
+        resource_dir=str(resource_path),
+        bundle_dir=str(bundle_path),
+        static_dir=str(static_path),
+        enable_ssr=enable_ssr,
+        enable_inertia=template.inertia_compatible and "inertia" in framework,
+        enable_types=True,
+    )
+
+    generate_project(root_path, context, overwrite=True)