ts-backend-check 1.2.2__py3-none-any.whl → 1.3.0__py3-none-any.whl

ts_backend_check/checker.py

@@ -3,11 +3,14 @@
 Main module for checking Django models against TypeScript types.
 """
 
-from typing import Dict, List, Set
+from typing import Dict, List, Tuple
 
-from ts_backend_check.parsers.django_parser import extract_model_fields
+from ts_backend_check.parsers.django_parser import (
+    DjangoModelVisitor,
+    extract_model_fields,
+)
 from ts_backend_check.parsers.typescript_parser import TypeScriptParser
-from ts_backend_check.utils import snake_to_camel
+from ts_backend_check.utils import is_ordered_subset, snake_to_camel
 
 
 class TypeChecker:
@@ -20,13 +23,30 @@ class TypeChecker:
         The file path for the models file to check.
 
     types_file : str
-        The file path for the TypeScript file to check.
+        The file path for the TypeScript interfaces file to check.
+
+    check_blank : bool, default=False
+        Whether to also check that fields marked 'blank=True' within Django models are optional (?) in the TypeScript interfaces.
+
+    model_name_conversions : dict[str: list[str]], default={}
+        A dictionary containing conversions of model names to their corresponding TypeScript interfaces.
     """
 
-    def __init__(self, models_file: str, types_file: str) -> None:
+    def __init__(
+        self,
+        models_file: str,
+        types_file: str,
+        check_blank: bool = False,
+        model_name_conversions: dict[str, list[str]] = {},
+    ) -> None:
         self.models_file = models_file
         self.types_file = types_file
-        self.model_fields = extract_model_fields(models_file)
+        self.check_blank = check_blank
+        self.model_name_conversions = model_name_conversions
+        self.django_model_visitor = DjangoModelVisitor
+        self.model_fields, self.models_and_blank_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_ignored_fields()
@@ -40,26 +60,56 @@ class TypeChecker:
         list
             A list of fields missing from the TypeScript file.
         """
-        missing_fields = []
+        error_fields: list[str] = []
 
         for model_name, fields in self.model_fields.items():
-            interfaces = self._find_matching_interfaces(model_name)
+            missing_fields_exist = False
+            interfaces, _ = self._find_matching_interfaces(model_name=model_name)
 
             if not interfaces:
-                missing_fields.append(
-                    self._format_missing_interface_message(model_name)
+                error_fields.append(
+                    self._format_missing_interface_message(model_name=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)
-            )
+            for field in fields:
+                if not self._field_is_accounted_for(field=field, interfaces=interfaces):
+                    error_fields.append(
+                        self._format_missing_field_message(
+                            field=field, model_name=model_name, interfaces=interfaces
+                        )
+                    )
+                    missing_fields_exist = True
+
+            if self.check_blank and model_name in self.models_and_blank_fields:
+                error_fields.extend(
+                    self._format_optional_properties_message(
+                        field=field,
+                        model_name=model_name,
+                        models_file=self.models_file,
+                        types_file=self.types_file,
+                    )
+                    for field in self.models_and_blank_fields[model_name]
+                    if not self._property_is_optional_when_field_is_blank(
+                        model_name=model_name,
+                        field=field,
+                    )
+                )
+
+            if not missing_fields_exist and not self._ts_interface_properties_ordered(
+                model_name=model_name, fields=fields
+            ):
+                error_fields.append(
+                    self._format_unordered_interface_properties_message(
+                        models_file=self.models_file, types_file=self.types_file
+                    )
+                )
 
-        return missing_fields
+        return error_fields
 
-    def _find_matching_interfaces(self, model_name: str) -> Dict[str, Set[str]]:
+    def _find_matching_interfaces(
+        self, model_name: str
+    ) -> Tuple[Dict[str, List[str]], Dict[str, List[str]]]:
         """
         Find matching TypeScript interfaces for a model.
 
@@ -70,44 +120,30 @@ class TypeChecker:
 
         Returns
         -------
-        Dict[str, Set[str]]
+        Tuple[Dict[str, List[str]], Dict[str, List[str]]]
             Interfaces that match a model name.
         """
-        potential_names = self._generate_potential_names(model_name)
-        return {
-            name: interface.fields
+        if self.model_name_conversions and model_name in self.model_name_conversions:
+            potential_names = self.model_name_conversions[model_name]
+
+        else:
+            potential_names = [model_name]
+
+        interfaces = {
+            name: interface.properties
+            for name, interface in self.ts_interfaces.items()
+            if any(potential == name for potential in potential_names)
+        }
+        interfaces_with_optional_properties = {
+            name: interface.optional_properties
             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]
+        return interfaces, interfaces_with_optional_properties
 
-    def _is_field_accounted_for(
-        self, field: str, interfaces: Dict[str, Set[str]]
+    def _field_is_accounted_for(
+        self, field: str, interfaces: Dict[str, List[str]]
     ) -> bool:
         """
         Check if a field is accounted for in TypeScript.
@@ -117,7 +153,7 @@ class TypeChecker:
         field : str
             The field that should be used in the frontend TypeScript file.
 
-        interfaces : Dict[str, Set[str]]
+        interfaces : Dict[str, List[str]]
             The interfaces from the frontend TypeScript file.
 
         Returns
@@ -132,6 +168,64 @@ class TypeChecker:
             or any(camel_field in fields for fields in interfaces.values())
         )
 
+    def _property_is_optional_when_field_is_blank(
+        self, model_name: str, field: str
+    ) -> bool:
+        """
+        Check that if the field is 'blank=True' that the corresponding interface property is optional (?).
+
+        Parameters
+        ----------
+        model_name : str
+            The name of the model to check the frontend TypeScript file for.
+
+        field : str
+            The field that should match the optional state of the property in the TypeScript file.
+
+        Returns
+        -------
+        Bool
+            Whether the blank status of the model field matches the optional status of the interface property.
+        """
+        camel_field = snake_to_camel(input_str=field)
+        _, interfaces_with_optional_properties = self._find_matching_interfaces(
+            model_name
+        )
+
+        return any(
+            camel_field in properties
+            for properties in interfaces_with_optional_properties.values()
+        )
+
+    def _ts_interface_properties_ordered(
+        self, model_name: str, fields: list[str]
+    ) -> bool:
+        """
+        Check if the order of the TypeScript interface properties exactly matches that of the backend model fields.
+
+        Parameters
+        ----------
+        model_name : str
+            The name of the model to check the frontend TypeScript file for.
+
+        fields : List[str]
+            The fields of the backend model.
+
+        Returns
+        -------
+        bool
+            Whether the order of the properties of the TypeScript interface file match that of the backend model fields.
+        """
+        camel_fields = [snake_to_camel(input_str=f) for f in fields]
+        interfaces, _ = self._find_matching_interfaces(model_name)
+
+        return all(
+            is_ordered_subset(
+                reference_list=camel_fields, candidate_sub_list=interfaces[i]
+            )
+            for i in interfaces
+        )
+
     @staticmethod
     def _format_missing_interface_message(model_name: str) -> str:
         """
@@ -147,15 +241,17 @@ class TypeChecker:
         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}"
-            f"\nSearched for interfaces: {', '.join(potential_names)}"
+            f"\nNo matching TypeScript interface found for the model '{model_name}'."
+            "\nPlease name your TypeScript interfaces the same as the corresponding backend models."
+            "\nYou can also use the 'backend_to_ts_model_name_conversions' option within the configuration file."
+            "\nThe key is the backend model name and the value is a list of the corresponding interfaces."
+            "\nThis option is also how you can break larger backend models into multiple interfaces that extend one another."
         )
 
     @staticmethod
     def _format_missing_field_message(
-        field: str, model_name: str, interfaces: Dict[str, Set[str]]
+        field: str, model_name: str, interfaces: Dict[str, List[str]]
     ) -> str:
         """
         Format message for missing field.
@@ -184,5 +280,64 @@ class TypeChecker:
         return (
             f"\nField '{field}' (camelCase: '{camel_field}') from model '{model_name}' is missing in the TypeScript interfaces."
             f"\nExpected to find this field in the frontend {interface_of_interfaces}: {', '.join(interfaces.keys())}"
-            f"\nTo ignore this field, add the following comment to the TypeScript file: '// ts-backend-check: ignore field {camel_field}'"
+            f"\nTo ignore this field, add the following comment to the TypeScript file (in order based on the model fields): '// ts-backend-check: ignore field {camel_field}'"
+        )
+
+    @staticmethod
+    def _format_optional_properties_message(
+        field: str, model_name: str, models_file: str, types_file: str
+    ) -> str:
+        """
+        Format message for when the blank status of a model field doesn't match the optional status of the corresponding property.
+
+        Parameters
+        ----------
+        field : str
+            The model field that doesn't match blank and optional states.
+
+        model_name : str
+            The name of the model that the mismatch occurs in.
+
+        models_file : str
+            The file path for the models file to check.
+
+        types_file : str
+            The file path for the TypeScript interfaces file that was checked.
+
+        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}' doesn't match the TypeScript interfaces based on blank to optional agreement."
+            f"\nPlease check '{models_file}' and '{types_file}' to make sure that all 'blank=True' fields are optional (?) in the TypeScript interfaces file."
+        )
+
+    @staticmethod
+    def _format_unordered_interface_properties_message(
+        models_file: str, types_file: str
+    ) -> str:
+        """
+        Format message for unordered interface properties.
+
+        Parameters
+        ----------
+        models_file : str
+            The file path for the models file to check.
+
+        types_file : str
+            The file path for the TypeScript interfaces file that was checked.
+
+        Returns
+        -------
+        str
+            The message displayed to the user when unordered interface properties are found.
+        """
+        return (
+            f"\nThe properties of the interface file '{types_file}' are unordered."
+            f"\nAll interface properties should exactly match the order of the corresponding fields in the '{models_file}' backend model."
+            "\nIf the model is synced with multiple interfaces, then their properties should follow the order prescribed by the model fields."
         )

ts_backend_check/cli/generate_config_file.py

@@ -0,0 +1,235 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""
+Configure cli to run based on a YAML configuration file.
+"""
+
+from pathlib import Path
+
+from rich import print as rprint
+from yaml import dump
+
+YAML_CONFIG_FILE_PATH = (
+    Path(__file__).parent.parent.parent.parent / ".ts-backend-check.yaml"
+)
+
+PROJECT_ROOT_PATH = Path(__file__).parent.parent.parent.parent
+
+
+def path_exists(path: str) -> bool:
+    """
+    Check if path entered by the user exists withing the filesystem.
+
+    Parameters
+    ----------
+    path : str
+        Path should be entered as a string from the user.
+
+    Returns
+    -------
+    bool
+        Return true or false based on if path exists.
+    """
+    full_path = Path(__file__).parent.parent.parent.parent / path
+    return bool(Path(full_path).is_file())
+
+
+def write_config(config: dict[str, dict[str, object]]) -> None:
+    """
+    Function to write into .ts-backend-check.yaml file.
+
+    Parameters
+    ----------
+    config : dict[str, dict[str, object]]
+        Passing a dictionary as key str with another dict as value.
+    """
+    try:
+        options = f"""# Configuration file for ts-backend-check validation.
+# See https://github.com/activist-org/ts-backend-check for details.
+
+{dump(config, sort_keys=False)}"""
+
+        with open(YAML_CONFIG_FILE_PATH, "w") as file:
+            file.write(options)
+
+    except IOError as e:
+        print(f"Error while writing configuration file: {e}")
+
+
+def configure_model_interface_arguments() -> None:
+    """
+    Function to receive paths from user.
+    """
+    config_options = {}
+    while True:
+        print(
+            "\nAdding new model-interface configuration. Please provide the information as directed:"
+        )
+
+        key = input(
+            "Enter a model-interface identifier (eg: auth, user, event): "
+        ).strip()
+        if not key:
+            rprint(
+                "\n[red]The model-interface identifier cannot be empty. Please try again.[/red]"
+            )
+            continue
+
+        # Get backend path.
+        while True:
+            backend_path = input("Enter the path for Django models.py file: ").strip()
+            if not backend_path:
+                rprint(
+                    "[red]The path for the Django models.py file cannot be empty. Please try again.[/red]"
+                )
+                continue
+
+            if path_exists(backend_path):
+                break
+
+            rprint(f"[red]File not found: {PROJECT_ROOT_PATH / backend_path}[/red]")
+            rprint("[yellow]Please check the path and try again.[/yellow]")
+
+        # Get frontend path.
+        while True:
+            frontend_path = input(
+                "Enter the path to TypeScript interface file: "
+            ).strip()
+            if not frontend_path:
+                rprint(
+                    "[red]The path for the TypeScript interface file cannot be empty. Please try again.[/red]"
+                )
+                continue
+
+            if path_exists(frontend_path):
+                break
+
+            rprint(f"[red]File not found: {PROJECT_ROOT_PATH / frontend_path}[/red]")
+            rprint("[yellow]Please check the path and try again.[/yellow]")
+
+        # Get whether to check blank model fields.
+        while True:
+            check_blank_model_fields_response = (
+                input(
+                    "The check should assert that model fields that can be blank must also be optional in interfaces ([y]/n): "
+                )
+                .strip()
+                .lower()
+            )
+
+            if check_blank_model_fields_response in ["y", ""]:
+                check_blank_model_fields = True
+                break
+
+            elif check_blank_model_fields_response == "n":
+                check_blank_model_fields = False
+                break
+
+            else:
+                rprint("[red]Invalid response. Please try again.[/red]")
+
+        # Get model name conversions.
+        rprint(
+            "[yellow]💡 Note: You need model name conversions if your TypeScript interfaces are not named exactly the same as the corresponding models (i.e. UserModel in Django and User in TS).[/yellow]"
+        )
+
+        backend_to_ts_model_name_conversions = {}
+        while True:
+            name_conversions_needed = (
+                input("Model name conversions are needed (y/[n]): ").strip().lower()
+            )
+
+            if name_conversions_needed in ["n", ""]:
+                break
+
+            while True:
+                while True:
+                    if backend_model_name := input(
+                        "Enter the backend model name: "
+                    ).strip():
+                        break
+
+                    else:
+                        rprint("[red]Invalid response. Please try again.[/red]")
+
+                while True:
+                    if ts_interface_name := input(
+                        "Enter the TypeScript interface name: "
+                    ).strip():
+                        break
+
+                    else:
+                        rprint("[red]Invalid response. Please try again.[/red]")
+
+                backend_to_ts_model_name_conversions[backend_model_name] = (
+                    ts_interface_name
+                )
+
+                further_name_conversions_needed = (
+                    input("Add more model name conversions (y/[n]): ").strip().lower()
+                )
+                if further_name_conversions_needed in ["n", ""]:
+                    break
+
+            break
+
+        config_options[key] = {
+            "backend_model_path": backend_path,
+            "ts_interface_path": frontend_path,
+            "check_blank_model_fields": check_blank_model_fields,
+        }
+
+        if backend_to_ts_model_name_conversions:
+            config_options[key]["backend_to_ts_model_name_conversions"] = (
+                backend_to_ts_model_name_conversions
+            )
+
+        write_config(config_options)
+        rprint(f"[green]✅ Added configuration for '{key}' check.[/green]")
+
+        continue_config = input(
+            "Add another model-interface configuration (y/[n]): "
+        ).strip()
+
+        if continue_config.lower() in ["n", ""]:
+            if config_options:
+                optional_s = "s" if len(config_options) > 1 else ""
+                rprint(
+                    f"[green]✅ Configuration complete! Added {len(config_options)} configuration{optional_s} to check.[/green]"
+                )
+            break
+
+
+def generate_config_file() -> None:
+    """
+    Main function to create or update configuration.
+    """
+    header = "ts-backend-check Configuration Setup"
+    print(header)
+    print("=" * len(header))
+
+    if YAML_CONFIG_FILE_PATH.is_file():
+        reconfigure_choice = input(
+            "Configuration file exists. Confirm if you want to re-configure your .ts-backend-check.yaml file (y/[n]): "
+        )
+        if reconfigure_choice.lower() in ["n", ""]:
+            print("Exiting without changes.")
+            return
+
+        print("Reconfiguring...")
+
+    else:
+        print("Creating new configuration file...")
+
+    try:
+        configure_model_interface_arguments()
+
+    except KeyboardInterrupt:
+        print("\n\nConfiguration cancelled by user.")
+
+    except Exception as e:
+        print(f"\nError during configuration: {e}")
+        print("Configuration cancelled.")
+
+
+if __name__ == "__main__":
+    generate_config_file()

ts_backend_check/cli/generate_test_project.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""
+Functionality to copy the test project files from the package to the present working directory.
+"""
+
+import os
+import shutil
+from pathlib import Path
+
+# Check for Windows and derive directory path separator.
+PATH_SEPARATOR = "\\" if os.name == "nt" else "/"
+INTERNAL_TEST_PROJECT_DIR_PATH = Path(__file__).parent.parent / "test_project"
+
+
+def generate_test_project() -> None:
+    """
+    Copy the ts_backend_check/test_project directory to the present working directory.
+    """
+    if not Path("./ts_backend_check_test_project/").is_dir():
+        print(
+            f"Generating testing project for ts-backend-check in .{PATH_SEPARATOR}ts_backend_check_test_project{PATH_SEPARATOR} ..."
+        )
+
+        shutil.copytree(
+            INTERNAL_TEST_PROJECT_DIR_PATH,
+            Path("./ts_backend_check_test_project/"),
+            dirs_exist_ok=True,
+        )
+
+        print("The test project has been successfully generated.")
+        print(
+            "Within the project there's one model that passes all checks and one that fails all checks."
+        )
+        if (
+            not Path(".ts-backend-check.yaml").is_file()
+            and not Path(".ts-backend-check.yml").is_file()
+        ):
+            print(
+                "You can set which one to test in an ts-backend-check configuration file."
+            )
+            print(
+                "Please generate one with the 'ts-backend-check --generate-config-file' command."
+            )
+
+        elif Path(".ts-backend-check.yaml").is_file():
+            print("You can set which one to test in the .ts-backend-check.yaml file.")
+
+        elif Path(".ts-backend-check.yml").is_file():
+            print("You can set which one to test in the .ts-backend-check.yml file.")
+
+    else:
+        print(
+            f"Test project for ts-backend-check already exist in .{PATH_SEPARATOR}ts_backend_check_test_project{PATH_SEPARATOR} and will not be regenerated."
+        )