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

ts_backend_check/cli/main.py

@@ -8,16 +8,137 @@ import sys
 from argparse import ArgumentParser
 from pathlib import Path
 
+import yaml
 from rich import print as rprint
 from rich.text import Text
 
 from ts_backend_check.checker import TypeChecker
-from ts_backend_check.cli.check_blank import check_blank
-from ts_backend_check.cli.config import create_config
+from ts_backend_check.cli.generate_config_file import generate_config_file
+from ts_backend_check.cli.generate_test_project import generate_test_project
 from ts_backend_check.cli.upgrade import upgrade_cli
 from ts_backend_check.cli.version import get_version_message
 
-ROOT_DIR = Path.cwd()
+# MARK: Base Paths
+
+CWD_PATH = Path.cwd()
+
+
+def get_config_file_path() -> Path:
+    """
+    Get the path to the ts-backend-check configuration file.
+
+    Checks for both .yaml and .yml extensions, preferring .yaml if both exist.
+
+    Returns
+    -------
+    Path
+        The path to the configuration file (.yaml or .yml).
+    """
+    yaml_path = CWD_PATH / ".ts-backend-check.yaml"
+    yml_path = CWD_PATH / ".ts-backend-check.yml"
+
+    # Prefer .yaml if it exists, otherwise check for .yml.
+    if yaml_path.is_file():
+        return yaml_path
+
+    elif yml_path.is_file():
+        return yml_path
+
+    else:
+        # Default to .yaml for new files.
+        return yaml_path
+
+
+YAML_CONFIG_FILE_PATH = get_config_file_path()
+
+
+# MARK: CLI Vars
+
+if not Path(YAML_CONFIG_FILE_PATH).is_file():
+    generate_config_file()
+
+if not Path(YAML_CONFIG_FILE_PATH).is_file():
+    print(
+        "No configuration file. Please generate a configuration file (.ts-backend-check.yaml or .ts-backend-check.yml) with ts-backend-check -gcf."
+    )
+    exit(1)
+
+with open(YAML_CONFIG_FILE_PATH, "r", encoding="utf-8") as file:
+    config = yaml.safe_load(file)
+
+
+def check_files_and_print_results(
+    identifier: str,
+    backend_model_file_path: Path,
+    ts_interface_file_path: Path,
+    check_blank: bool = False,
+    model_name_conversions: dict[str, list[str]] = {},
+) -> bool:
+    """
+    Check the provided files for the given model and print the results.
+
+    Parameters
+    ----------
+    identifier : str
+        The model in the .ts-backend-check.yaml configuration file to check models and interfaces for.
+
+    backend_model_file_path : Path
+        The path to the backend models as defined in the .ts-backend-check.yaml configuration file.
+
+    ts_interface_file_path : Path
+        The path to the TypeScript interfaces as defined in the .ts-backend-check.yaml configuration file.
+
+    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 of backend model names to their corresponding TypeScript interfaces when snake to camel case isn't valid.
+
+    Returns
+    -------
+    bool
+        Whether the checks passed (True) or not (False).
+    """
+    if not backend_model_file_path.is_file():
+        rprint(
+            f"[red]❌ {backend_model_file_path} that should contain the '{identifier}' backend models does not exist. Please check the ts-backend-check configuration file and try again.[/red]"
+        )
+        return False
+
+    elif not ts_interface_file_path.is_file():
+        rprint(
+            f"[red]❌ {ts_interface_file_path} that should contain the '{identifier}' TypeScript types does not exist. Please check the ts-backend-check configuration file and try again.[/red]"
+        )
+        return False
+
+    checker = TypeChecker(
+        models_file=str(backend_model_file_path),
+        types_file=str(ts_interface_file_path),
+        model_name_conversions=model_name_conversions,
+        check_blank=check_blank,
+    )
+
+    if missing := checker.check():
+        rprint(
+            f"\n[red]❌ ts-backend-check error: There are inconsistencies between the provided '{identifier}' backend models and TypeScript interfaces. Please see the output below for details.[/red]"
+        )
+
+        for msg in missing:
+            rprint(Text.from_markup(f"[red]{msg}[/red]"))
+
+        error_or_errors = "errors" if len(missing) > 1 else "error"
+        rprint(
+            f"[red]\nPlease fix the {len(missing)} {error_or_errors} above to continue the sync of the backend models of {backend_model_file_path} and the TypeScript interfaces of {ts_interface_file_path}.[/red]"
+        )
+
+        return False
+
+    else:
+        rprint(
+            f"[green]✅ Success: All backend models are synced with their corresponding TypeScript interfaces for the provided '{identifier}' files.[/green]"
+        )
+
+        return True
 
 
 def main() -> None:
@@ -27,12 +148,19 @@ def main() -> None:
     Notes
     -----
     The available command line arguments are:
-    - --backend-model-file (-bmf): Path to the backend model file (e.g. Python class)
-    - --typescript-file (-tsf): Path to the TypeScript interface/type file
+    - --help (-h): Show this help message and exit.
+    - --version (-v): Show the version of the ts-backend-check CLI.
+    - --upgrade (-u): Upgrade the ts-backend-check CLI to the latest version.
+    - --generate-config-file (-gcf): Interactively generate a configuration file for ts-backend-check.
+    - --generate-test-project (-gtp): Generate project to test ts-backend-check functionalities.
+    - --model (-m): The model in the .ts-backend-check.yaml configuration file to check.
+    - --all (-a): Run checks of all backend models against their corresponding TypeScript interfaces.
 
     Examples
     --------
-    >>> ts-backend-check -bmf <backend-model-file> -tsf <typescript-file>
+    >>> ts-backend-check --generate-config-file  # -gcf
+    >>> ts-backend-check --model <ts-backend-check-config-file-model>  # -m
+    >>> ts-backend-check --all  # -a
     """
     # MARK: CLI Base
 
@@ -61,28 +189,30 @@ def main() -> None:
     )
 
     parser.add_argument(
-        "-bmf",
-        "--backend-model-file",
-        help="Path to the backend model file (e.g. Python class).",
+        "-gcf",
+        "--generate-config-file",
+        action="store_true",
+        help="Interactively generate a configuration file for ts-backend-check.",
     )
 
     parser.add_argument(
-        "-tsf",
-        "--typescript-file",
-        help="Path to the TypeScript interface/type file.",
+        "-gtp",
+        "--generate-test-project",
+        action="store_true",
+        help="Generate project to test ts-backend-check functionalities.",
     )
 
     parser.add_argument(
-        "-c",
-        "--configure",
-        action="store_true",
-        help="Configure a YAML file to simplify your checks.",
+        "-m",
+        "--model",
+        help="The model in the .ts-backend-check.yaml configuration file to check.",
     )
 
     parser.add_argument(
-        "-cb",
-        "--check-blank",
-        help="Check for fields marked blank=True within Django models.",
+        "-a",
+        "--all",
+        action="store_true",
+        help="Run checks of all backend models against their corresponding TypeScript interfaces.",
     )
 
     # MARK: Setup CLI
@@ -93,53 +223,84 @@ def main() -> None:
         upgrade_cli()
         return
 
-    if args.configure:
-        create_config()
+    if args.generate_config_file:
+        generate_config_file()
         return
 
-    if args.check_blank:
-        check_blank(args.check_blank)
+    if args.generate_test_project:
+        generate_test_project()
         return
 
-    # MARK: Run Check
+    # MARK: Run Checks
 
-    backend_model_file_path = ROOT_DIR / args.backend_model_file
-    ts_file_path = ROOT_DIR / args.typescript_file
+    results = []
 
-    if not backend_model_file_path.is_file():
-        rprint(
-            f"[red]{args.backend_model_file} that should contain the backend models does not exist. Please check and try again.[/red]"
-        )
+    if args.model:
+        model_config = config.get(args.model)
 
-    elif not ts_file_path.is_file():
-        rprint(
-            f"[red]{args.typescript_file} file that should contain the TypeScript types does not exist. Please check and try again.[/red]"
-        )
+        if not model_config:
+            rprint(
+                f"[red]{args.model} is not an index within the .ts-backend-check.yaml configuration file. Please check the defined models and try again.[/red]"
+            )
+            sys.exit(1)
 
-    else:
-        checker = TypeChecker(
-            models_file=args.backend_model_file,
-            types_file=args.typescript_file,
+        config_backend_model_file_path = Path(model_config["backend_model_path"])
+        config_ts_interface_file_path = Path(model_config["ts_interface_path"])
+        config_check_blank = (
+            model_config["check_blank_model_fields"]
+            if "check_blank_model_fields" in model_config
+            else False
+        )
+        config_model_name_conversions = (
+            model_config["backend_to_ts_model_name_conversions"]
+            if "backend_to_ts_model_name_conversions" in model_config
+            else {}
         )
 
-        if missing := checker.check():
-            rprint(
-                "\n[red]❌ ts-backend-check error: There are inconsistencies between the provided backend models and TypeScript interfaces. Please see the output below for details.[/red]"
+        r = check_files_and_print_results(
+            identifier=args.model,
+            backend_model_file_path=config_backend_model_file_path,
+            ts_interface_file_path=config_ts_interface_file_path,
+            check_blank=config_check_blank,
+            model_name_conversions=config_model_name_conversions,
+        )
+        results.append(r)
+
+    if args.all:
+        for i in config.keys():
+            model_config = config.get(i)
+
+            config_backend_model_file_path = Path(model_config["backend_model_path"])
+            config_ts_interface_file_path = Path(model_config["ts_interface_path"])
+            config_check_blank = (
+                model_config["check_blank_model_fields"]
+                if "check_blank_model_fields" in model_config
+                else False
+            )
+            config_model_name_conversions = (
+                model_config["backend_to_ts_model_name_conversions"]
+                if "backend_to_ts_model_name_conversions" in model_config
+                else {}
             )
 
-            # Print each error message in red.
-            for msg in missing:
-                rprint(Text.from_markup(f"[red]{msg}[/red]"))
-
-            field_or_fields = "fields" if len(missing) > 1 else "field"
-            rprint(
-                f"[red]\nPlease fix the {len(missing)} {field_or_fields} above to have the backend models of {args.backend_model_file} synced with the typescript interfaces of {(args.typescript_file)}.[/red]"
+            r = check_files_and_print_results(
+                identifier=i,
+                backend_model_file_path=config_backend_model_file_path,
+                ts_interface_file_path=config_ts_interface_file_path,
+                check_blank=config_check_blank,
+                model_name_conversions=config_model_name_conversions,
             )
+            results.append(r)
+
+    if args.model or args.all:
+        if not all(results):
             sys.exit(1)
 
-        rprint(
-            "[green]✅ Success: All backend models are synced with their corresponding TypeScript interfaces for the provided files.[/green]"
-        )
+        else:
+            return  # exit 0
+
+    else:
+        parser.print_help()
 
 
 if __name__ == "__main__":

ts_backend_check/parsers/django_parser.py

@@ -4,7 +4,7 @@ Module for parsing Django models and extracting field information.
 """
 
 import ast
-from typing import Dict, Set
+from typing import Dict, List, Tuple
 
 
 class DjangoModelVisitor(ast.NodeVisitor):
@@ -31,8 +31,9 @@ class DjangoModelVisitor(ast.NodeVisitor):
     }
 
     def __init__(self) -> None:
-        self.models: Dict[str, Set[str]] = {}
+        self.models: Dict[str, List[str]] = {}
         self.current_model: str | None = None
+        self.models_and_blank_fields: Dict[str, List[str]] = {}
 
     def visit_ClassDef(self, node: ast.ClassDef) -> None:
         """
@@ -48,7 +49,7 @@ class DjangoModelVisitor(ast.NodeVisitor):
         if node.bases:
             self.current_model = node.name
             if self.current_model not in self.models:
-                self.models[self.current_model] = set()
+                self.models[self.current_model] = []
 
             self.generic_visit(node)
 
@@ -77,10 +78,23 @@ class DjangoModelVisitor(ast.NodeVisitor):
                 field_type in node.value.func.attr
                 for field_type in self.DJANGO_FIELD_TYPES
             ):
-                self.models[self.current_model].add(target.id)
+                self.models[self.current_model].append(target.id)
 
+                if any(
+                    kw.arg == "blank"
+                    and isinstance(kw.value, ast.Constant)
+                    and kw.value.value is True
+                    for kw in node.value.keywords
+                ):
+                    if self.current_model not in self.models_and_blank_fields:
+                        self.models_and_blank_fields[self.current_model] = []
 
-def extract_model_fields(models_file: str) -> Dict[str, Set[str]]:
+                    self.models_and_blank_fields[self.current_model].append(target.id)
+
+
+def extract_model_fields(
+    models_file: str,
+) -> Tuple[Dict[str, List[str]], Dict[str, List[str]]]:
     """
     Extract fields from Django models file.
 
@@ -91,7 +105,7 @@ def extract_model_fields(models_file: str) -> Dict[str, Set[str]]:
 
     Returns
     -------
-    Dict[str, Set[str]]
+    Tuple(Dict[str, List[str]], Dict[str, List[str]])
         The fields from the models file extracted into a dictionary for future processing.
     """
     with open(models_file, "r", encoding="utf-8") as f:
@@ -102,6 +116,7 @@ def extract_model_fields(models_file: str) -> Dict[str, Set[str]]:
 
     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)}"
@@ -110,4 +125,4 @@ def extract_model_fields(models_file: str) -> Dict[str, Set[str]]:
     visitor = DjangoModelVisitor()
     visitor.visit(tree)
 
-    return visitor.models
+    return visitor.models, visitor.models_and_blank_fields

ts_backend_check/parsers/typescript_parser.py

@@ -11,11 +11,12 @@ from typing import Dict, List, Set
 @dataclass
 class TypeScriptInterface:
     """
-    Represents a TypeScript interface with its fields and parent interfaces.
+    Represents a TypeScript interface with its properties and parent interfaces.
     """
 
     name: str
-    fields: Set[str]
+    properties: List[str]
+    optional_properties: List[str]
     parents: List[str]
 
 
@@ -54,9 +55,12 @@ class TypeScriptParser:
             parents = (
                 [p.strip() for p in match.group(2).split(",")] if match.group(2) else []
             )
-            fields = self._extract_fields(match.group(3))
+            properties = self._extract_properties(match.group(3))
+            optional_properties = self._extract_optional_properties(match.group(3))
 
-            interfaces[name] = TypeScriptInterface(name, fields, parents)
+            interfaces[name] = TypeScriptInterface(
+                name, properties, optional_properties, parents
+            )
 
         return interfaces
 
@@ -73,9 +77,9 @@ class TypeScriptParser:
         return set(re.findall(ignore_pattern, self.content))
 
     @staticmethod
-    def _extract_fields(interface_body: str) -> Set[str]:
+    def _extract_properties(interface_body: str) -> List[str]:
         """
-        Extract field names from interface body.
+        Extract both real properties and 'ignored' comment backend fields from interface bodies.
 
         Parameters
         ----------
@@ -84,15 +88,43 @@ class TypeScriptParser:
 
         Returns
         -------
-        Set[str]
-            The field names from the model interface body.
+        List[str]
+            The property names from the model interface body.
+        """
+        combined_pattern = (
+            r"^\s*(?:"
+            r"(?:readonly\s+)?(\w+)\s*\??\s*:|"  # standard/readonly properties
+            r"//\s*ts-backend-check:\s*ignore\s+field\s+(\w+)"  # ts-backend-check ignore comment properties
+            r")"
+        )
+
+        properties = []
+        for match in re.finditer(combined_pattern, interface_body, flags=re.MULTILINE):
+            if field_name := match.group(1) or match.group(2):
+                properties.append(field_name)
+
+        return properties
+
+    @staticmethod
+    def _extract_optional_properties(interface_body: str) -> List[str]:
         """
-        fields = set()
+        Extract all optional properties from interface bodies.
 
-        # Regular fields
-        fields.update(re.findall(r"(?://[^\n]*\n)*\s*(\w+)\s*[?]?\s*:", interface_body))
+        Parameters
+        ----------
+        interface_body : str
+            A string representation of the interface body of the model.
+
+        Returns
+        -------
+        List[str]
+            The optional property names from the model interface body.
+        """
+        pattern = r"^\s*(?:readonly\s+)?(\w+)\s*\?:"  # optional properties
 
-        # Readonly fields
-        fields.update(re.findall(r"readonly\s+(\w+)\s*[?]?\s*:", interface_body))
+        optional_properties = []
+        for match in re.finditer(pattern, interface_body, flags=re.MULTILINE):
+            if field_name := match.group(1):
+                optional_properties.append(field_name)
 
-        return fields
+        return optional_properties

ts_backend_check/test_project/backend/models.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""
+Example backend model file that has both valid and invalid TS interface files in test_project/frontend.
+"""
+
+from django.db import models
+
+# mypy: ignore-errors
+
+
+class EventModel(models.Model):
+    """
+    Model for events that has both valid and invalid corresponding TS interface files.
+    """
+
+    title = models.CharField(max_length=200)
+    description = models.TextField()
+    organizer = models.ForeignKey("User", on_delete=models.CASCADE)
+    participants = models.ManyToManyField("User", related_name="events", blank=True)
+    is_private = models.BooleanField(default=True)
+    date = models.DateTimeField()
+    _private_field = models.CharField(max_length=100)  # should be ignored
+
+
+class UserModel(models.Model):
+    """
+    Model for users that has both valid and invalid corresponding TS interface files.
+    """
+
+    id = models.CharField(max_length=32)
+    name = models.CharField(max_length=50)

ts_backend_check/test_project/frontend/invalid_interfaces.ts

@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+// Attn: EventModel is missing a field from backend/models.py.
+export interface Event {
+  // Note: EventModel is mapped to Event and EventExtended via backend_to_ts_model_name_conversions.
+  title: string;
+  organizer: User;
+  // Attn: participants is not optional.
+  participants: User[];
+}
+
+export interface EventExtended extends Event {
+  // Attn: date is out of order below, but this won't be reported as we have missing fields.
+  // ts-backend-check: ignore field date
+  isPrivate: boolean;
+}
+
+// Attn: User is not synced to UserModel via backend_to_ts_model_name_conversions.
+export interface User {
+  id: string;
+  name: string;
+}

ts_backend_check/test_project/frontend/valid_interfaces.ts

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: GPL-3.0-or-later
+export interface Event {
+  // Note: EventModel is mapped to Event and EventExtended via backend_to_ts_model_name_conversions.
+  title: string;
+  description: string;
+  organizer: User;
+  participants?: User[];
+}
+
+export interface EventExtended extends Event {
+  isPrivate: boolean;
+  // ts-backend-check: ignore field date
+}
+
+export interface User {
+  id: string;
+  name: string;
+}

ts_backend_check/utils.py

@@ -3,6 +3,8 @@
 Utility functions for ts-backend-check.
 """
 
+from typing import Any
+
 
 def snake_to_camel(input_str: str) -> str:
     """
@@ -20,7 +22,8 @@ def snake_to_camel(input_str: str) -> str:
 
     Examples
     --------
-    hello_world -> helloWorld, alreadyCamelCase -> alreadyCamelCase
+    hello_world -> helloWorld
+    alreadyCamelCase -> alreadyCamelCase
     """
     if not input_str or input_str.startswith("_"):
         return input_str
@@ -37,3 +40,24 @@ def snake_to_camel(input_str: str) -> str:
                 result += word[0].upper() + word[1:].lower()
 
     return result
+
+
+def is_ordered_subset(reference_list: list[Any], candidate_sub_list: list[Any]) -> bool:
+    """
+    Return True if candidate elements appear in the same relative order as they do in the reference.
+
+    Parameters
+    ----------
+    reference_list : list
+        The original list to reference.
+
+    candidate_sub_list : list
+        A potential list that has elements that are in the same relative order to the reference.
+
+    Returns
+    -------
+    bool
+        Whether the candidate elements appear in the same relative order as they do in the reference.
+    """
+    it = iter(reference_list)
+    return all(item in it for item in candidate_sub_list)