ts-backend-check 1.0.0__py3-none-any.whl

ts_backend_check/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+__version__ = "1.0.0"
+
+from .checker import TypeChecker
+from .cli import cli
+
+__all__ = ["cli", "TypeChecker"]

ts_backend_check/checker.py

@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""
+Main module for checking Django models against TypeScript types.
+"""
+
+from typing import Dict, List, Set
+
+from .django_parser import extract_model_fields
+from .typescript_parser import TypeScriptParser
+from .utils import snake_to_camel
+
+
+class TypeChecker:
+    """
+    Main class for checking Django models against TypeScript types.
+
+    Parameters
+    ----------
+    models_file : str
+        The file path for the models file to check.
+
+    types_file : str
+        The file path for the TypeScript file to check.
+    """
+
+    def __init__(self, models_file: str, types_file: str) -> None:
+        self.models_file = models_file
+        self.types_file = types_file
+        self.model_fields = extract_model_fields(models_file)
+        self.ts_parser = TypeScriptParser(types_file)
+        self.ts_interfaces = self.ts_parser.parse_interfaces()
+        self.backend_only = self.ts_parser.get_backend_only_fields()
+
+    def check(self) -> List[str]:
+        """
+        Check models against TypeScript types.
+
+        Returns
+        -------
+        list
+            A list of fields missing from the TypeScript file.
+        """
+        missing_fields = []
+
+        for model_name, fields in self.model_fields.items():
+            interfaces = self._find_matching_interfaces(model_name)
+
+            if not interfaces:
+                missing_fields.append(
+                    self._format_missing_interface_message(model_name)
+                )
+                continue
+
+            missing_fields.extend(
+                self._format_missing_field_message(field, model_name, interfaces)
+                for field in fields
+                if not self._is_field_accounted_for(field, interfaces)
+            )
+
+        return missing_fields
+
+    def _find_matching_interfaces(self, model_name: str) -> Dict[str, Set[str]]:
+        """
+        Find matching TypeScript interfaces for a model.
+
+        Parameters
+        ----------
+        model_name : str
+            The name of the model to check the frontend TypeScript file for.
+
+        Returns
+        -------
+        Dict[str, Set[str]]
+            Interfaces that match a model name.
+        """
+        potential_names = self._generate_potential_names(model_name)
+        return {
+            name: interface.fields
+            for name, interface in self.ts_interfaces.items()
+            if any(potential == name for potential in potential_names)
+        }
+
+    @staticmethod
+    def _generate_potential_names(model_name: str) -> List[str]:
+        """
+        Generate potential TypeScript interface names for a model.
+
+        Parameters
+        ----------
+        model_name : str
+            The name of the model to check the frontend TypeScript file for.
+
+        Returns
+        -------
+        List[str]
+            Possible names for the model to check for.
+        """
+        base_names = [
+            model_name,
+            model_name.replace("Model", ""),
+        ]
+
+        if "_" in model_name:
+            base_names.append(snake_to_camel(input_str=model_name))
+
+        suffixes = ["", "Base", "Response", "Type"]
+        return [f"{base}{suffix}" for base in base_names for suffix in suffixes]
+
+    def _is_field_accounted_for(
+        self, field: str, interfaces: Dict[str, Set[str]]
+    ) -> bool:
+        """
+        Check if a field is accounted for in TypeScript.
+
+        Parameters
+        ----------
+        field : str
+            The field that should be used in the frontend TypeScript file.
+
+        interfaces : Dict[str, Set[str]]
+            The interfaces from the frontend TypeScript file.
+
+        Returns
+        -------
+        Bool
+            Whether the field is accounted for in the frontend TypeScript file.
+        """
+        camel_field = snake_to_camel(input_str=field)
+        return (
+            camel_field in self.backend_only
+            or field in self.backend_only
+            or any(camel_field in fields for fields in interfaces.values())
+        )
+
+    @staticmethod
+    def _format_missing_interface_message(model_name: str) -> str:
+        """
+        Format message for missing interface.
+
+        Parameters
+        ----------
+        model_name : str
+            The name of the model that an interface is missing from.
+
+        Returns
+        -------
+        str
+            The message displayed to the user when missing interfaces are found.
+        """
+        potential_names = TypeChecker._generate_potential_names(model_name)
+        return (
+            f"\nNo matching TypeScript interface found for model: {model_name}\n"
+            f"Searched for interfaces: {', '.join(potential_names)}"
+        )
+
+    @staticmethod
+    def _format_missing_field_message(
+        field: str, model_name: str, interfaces: Dict[str, Set[str]]
+    ) -> str:
+        """
+        Format message for missing field.
+
+        Parameters
+        ----------
+        field : str
+            The model field that's missing.
+
+        model_name : str
+            The name of the model that the field is missing from.
+
+        interfaces : Dict[str, Set[str]]
+            The interfaces that have been searched.
+
+        Returns
+        -------
+        str
+            The message displayed to the user when missing fields are found.
+        """
+        camel_field = snake_to_camel(input_str=field)
+        return (
+            f"\nField '{field}' (camelCase: '{camel_field}') from model '{model_name}' "
+            f"is missing in TypeScript types.\n"
+            f"Expected to find in interface(s): {', '.join(interfaces.keys())}\n"
+            f"To ignore this field, add a comment that references it like: '// Note: {camel_field} is backend only'"
+        )

ts_backend_check/cli/__init__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+"""
+CLI package for ts-backend-check.
+"""
+
+from .main import cli
+
+__all__ = ["cli"]

ts_backend_check/cli/main.py

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""
+Setup and commands for the ts-backend-check command line interface.
+"""
+
+import sys
+
+import click
+
+from ..checker import TypeChecker
+
+
+@click.group()
+@click.version_option()
+def cli():
+    """
+    TS Backend Check is a Python package used to check TypeScript types against their corresponding backend models.
+    """
+    pass
+
+
+@cli.command()
+@click.argument("backend_model", type=click.Path(exists=True))
+@click.argument("typescript_file", type=click.Path(exists=True))
+def check(backend_model: str, typescript_file: str):
+    """
+    Check TypeScript types against backend models.
+
+    This command checks if all fields from the backend model are properly represented
+    in the TypeScript types file. It supports marking fields as backend-only using
+    special comments in the TypeScript file.
+
+    Parameters
+    ----------
+    backend_model : str
+        The path to the backend model file (e.g. Python class).
+
+    typescript_file : str
+        The path to the TypeScript interface/type file.
+
+    Examples
+    --------
+    ts-backend-check check src/models/user.py src/types/user.ts
+    """
+    checker = TypeChecker(models_file=backend_model, types_file=typescript_file)
+    if missing := checker.check():
+        click.echo("Missing TypeScript fields found:")
+        click.echo("\n".join(missing))
+        click.echo(
+            f"\nPlease correct the {len(missing)} fields above to have backend models and frontend types fully synced."
+        )
+        sys.exit(1)
+
+    click.echo("All model fields are properly typed in TypeScript!")
+
+
+if __name__ == "__main__":
+    cli()

ts_backend_check/django_parser.py

@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""
+Module for parsing Django models and extracting field information.
+"""
+
+import ast
+from typing import Dict, Set
+
+
+class DjangoModelVisitor(ast.NodeVisitor):
+    """
+    AST visitor to extract fields from Django models.
+    """
+
+    DJANGO_FIELD_TYPES = {
+        "Field",
+        "CharField",
+        "TextField",
+        "IntegerField",
+        "BooleanField",
+        "DateTimeField",
+        "ForeignKey",
+        "ManyToManyField",
+        "OneToOneField",
+        "EmailField",
+        "URLField",
+        "FileField",
+        "ImageField",
+        "DecimalField",
+        "AutoField",
+    }
+
+    def __init__(self) -> None:
+        self.models: Dict[str, Set[str]] = {}
+        self.current_model: str | None = None
+
+    def visit_ClassDef(self, node: ast.ClassDef) -> None:
+        """
+        Check class definitions, specifically those that inherit from other classes.
+
+        Parameters
+        ----------
+        node : ast.ClassDef
+            A class definition from Python AST (Abstract Syntax Tree).
+            It contains information about the class, such as its name, base classes, body, decorators, etc.
+        """
+        # Only process classes that inherit from something.
+        if node.bases:
+            self.current_model = node.name
+            if self.current_model not in self.models:
+                self.models[self.current_model] = set()
+
+            self.generic_visit(node)
+
+        self.current_model = None
+
+    def visit_Assign(self, node: ast.Assign) -> None:
+        """
+        Check assignment statements within a class.
+
+        Parameters
+        ----------
+        node : ast.Assign
+            An assignment definition from Python AST (Abstract Syntax Tree).
+            It represents an assignment statement (e.g., x = 42).
+        """
+        if not self.current_model:
+            return
+
+        for target in node.targets:
+            if (
+                isinstance(target, ast.Name)
+                and not target.id.startswith("_")
+                and isinstance(node.value, ast.Call)
+                and hasattr(node.value.func, "attr")
+            ) and any(
+                field_type in node.value.func.attr
+                for field_type in self.DJANGO_FIELD_TYPES
+            ):
+                self.models[self.current_model].add(target.id)
+
+
+def extract_model_fields(models_file: str) -> Dict[str, Set[str]]:
+    """
+    Extract fields from Django models file.
+
+    Parameters
+    ----------
+    models_file : str
+        A models.py file that defines Django models.
+
+    Returns
+    -------
+    Dict[str, Set[str]]
+        The fields from the models file extracted into a dictionary for future processing.
+    """
+    with open(models_file, "r", encoding="utf-8") as f:
+        content = f.read().strip()
+        # Skip any empty lines at the beginning
+        while content.startswith("\n"):
+            content = content[1:]
+
+    try:
+        tree = ast.parse(content)
+    except SyntaxError as e:
+        raise SyntaxError(
+            f"Failed to parse {models_file}. Make sure it's a valid Python file. Error: {str(e)}"
+        ) from e
+
+    visitor = DjangoModelVisitor()
+    visitor.visit(tree)
+
+    return visitor.models

ts_backend_check/typescript_parser.py

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""
+Module for parsing TypeScript interfaces and types.
+"""
+
+import re
+from dataclasses import dataclass
+from typing import Dict, List, Set
+
+
+@dataclass
+class TypeScriptInterface:
+    """
+    Represents a TypeScript interface with its fields and parent interfaces.
+    """
+
+    name: str
+    fields: Set[str]
+    parents: List[str]
+
+
+class TypeScriptParser:
+    """
+    Parser for TypeScript interface files.
+
+    Parameters
+    ----------
+    file_path : str
+        The file path for the TypeScript file to parse.
+    """
+
+    def __init__(self, file_path: str) -> None:
+        self.file_path = file_path
+        with open(file_path, "r", encoding="utf-8") as f:
+            self.content = f.read()
+
+    def parse_interfaces(self) -> Dict[str, TypeScriptInterface]:
+        """
+        Parse TypeScript interfaces from the file.
+
+        Returns
+        -------
+        Dict[str, TypeScriptInterface]
+            The interface parsed into a dictionary for future processing.
+        """
+        interfaces = {}
+        interface_pattern = (
+            r"(?:export\s+|declare\s+)?interface\s+(\w+)"
+            r"(?:\s+extends\s+([^{]+))?\s*{([\s\S]*?)}"
+        )
+
+        for match in re.finditer(interface_pattern, self.content):
+            name = match.group(1)
+            parents = (
+                [p.strip() for p in match.group(2).split(",")] if match.group(2) else []
+            )
+            fields = self._extract_fields(match.group(3))
+
+            interfaces[name] = TypeScriptInterface(name, fields, parents)
+
+        return interfaces
+
+    def get_backend_only_fields(self) -> Set[str]:
+        """
+        Extract fields marked as backend-only in comments.
+
+        Returns
+        -------
+        Set[str]
+            The field names that are marked with a backend-only identifier to ignore them.
+        """
+        patterns = [
+            r"//.*?Note:\s*(\w+)\s+is\s+backend\s+only",
+            r"//.*?(\w+)\s+is\s+backend\s+only",
+            r"//\s*@backend-only\s+(\w+)",
+            r"//.*?backend-only:\s*(\w+)",
+        ]
+        return {
+            match for pattern in patterns for match in re.findall(pattern, self.content)
+        }
+
+    @staticmethod
+    def _extract_fields(interface_body: str) -> Set[str]:
+        """
+        Extract field names from interface body.
+
+        Parameters
+        ----------
+        interface_body : str
+            A string representation of the interface body of the model.
+
+        Returns
+        -------
+        Set[str]
+            The field names from the model interface body.
+        """
+        fields = set()
+
+        # Regular fields
+        fields.update(re.findall(r"(?://[^\n]*\n)*\s*(\w+)\s*[?]?\s*:", interface_body))
+
+        # Readonly fields
+        fields.update(re.findall(r"readonly\s+(\w+)\s*[?]?\s*:", interface_body))
+
+        return fields

ts_backend_check/utils.py

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""
+Utility functions for ts-backend-check.
+"""
+
+
+def snake_to_camel(input_str: str) -> str:
+    """
+    Convert snake_case to camelCase.
+
+    Parameters
+    ----------
+    input_str : str
+        The snake_case string to convert.
+
+    Returns
+    -------
+    str
+        The camelCase version of the input string.
+    """
+    components = input_str.split("_")
+    return components[0] + "".join(x.title() for x in components[1:])

ts_backend_check-1.0.0.data/data/requirements.txt

@@ -0,0 +1,6 @@
+#
+# This file is autogenerated by pip-compile with Python 3.13
+# by the following command:
+#
+#    pip-compile requirements.in
+#