Coverage for src / lexigram / contracts / codegen / protocols.py: 0%

1"""Codegen protocols for Lexigram framework.""" 

2 

3from __future__ import annotations 

4 

5from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable 

6 

7if TYPE_CHECKING: 

8 from lexigram.contracts.cli.generators import GenerationResult 

9 

10 

11@runtime_checkable 

12class ScaffoldGeneratorProtocol(Protocol): 

13 """Interactive code scaffolder invoked via CLI. 

14 

15 Scaffolders are name-based generators that produce files on disk. 

16 They are registered via entry points and invoked by the ``lexigram generate`` 

17 CLI command. 

18 

19 Example: 

20 ```python 

21 class MyGenerator: 

22 name = "mygen" 

23 description = "Generates a mygen" 

24 

25 def generate(self, name: str, **options: Any) -> GenerationResult: 

26 # ... create files ... 

27 return GenerationResult(files_created=[...]) 

28 ``` 

29 """ 

30 

31 name: str 

32 description: str 

33 

34 def generate(self, name: str, **options: Any) -> GenerationResult: # noqa: UP037 

35 """Generate files for the given name. 

36 

37 Args: 

38 name: The name to generate code for (e.g. module name, provider name). 

39 **options: Additional generation parameters such as output_dir, dry_run, force. 

40 

41 Returns: 

42 A ``GenerationResult`` describing which files were created/skipped/overwritten. 

43 """ 

44 ... 

45 

46 

47@runtime_checkable 

48class TemplateGeneratorProtocol(Protocol): 

49 """Programmatic template renderer invoked by admin/plugin system. 

50 

51 Template renderers are context-based generators that return rendered objects 

52 rather than writing to disk. They are invoked by the admin dashboard or 

53 plugin system when rendering configuration templates. 

54 

55 Example: 

56 ```python 

57 class AuthPolicyGenerator: 

58 def generate(self, context: dict[str, object]) -> list[object]: 

59 return [ 

60 PolicyRule(allow=["admin:*"]), 

61 PolicyRule(allow=["user:read"]), 

62 ] 

63 ``` 

64 """ 

65 

66 def generate(self, context: dict[str, object]) -> list[object]: 

67 """Render a template with the given context. 

68 

69 Args: 

70 context: A dictionary of template variables and their values. 

71 

72 Returns: 

73 A list of rendered objects (e.g. policy rules, config objects). 

74 """ 

75 ... 

76 

77 

78__all__ = ["ScaffoldGeneratorProtocol", "TemplateGeneratorProtocol"]