lua-annotations 0.1.0__py3-none-any.whl

lua_annotations/extensions/game_framework/main.py

@@ -0,0 +1,8 @@
+from lua_annotations.api.annotations import ExtensionRegistry
+from . import lifecycle, index, networking
+
+
+def load(ctx: ExtensionRegistry):
+    ctx.register_extension(index.IndexExtension())
+    ctx.register_extension(lifecycle.LifecycleExtension(), deps=['ManifestExtension'], hook_order='before')
+    ctx.register_extension(networking.NetworkingExtension())

lua_annotations/extensions/game_framework/networking.py

@@ -0,0 +1,65 @@
+from typing import Any
+
+from lua_annotations.api.annotations import AnnotationBuildCtx, AnnotationDef, ExtensionRegistry, Extension
+from lua_annotations.build_process import PostProcessCtx
+from lua_annotations.parser_schemas import Annotation, LuaMethod
+
+REMOTE_INSTANCE_MAP = {
+    'function': 'RemoteFunction',
+    'event': 'RemoteEvent',
+    'unreliable': 'UnreliableRemoteEvent',
+}
+
+
+class NetworkingExtension(Extension):
+    def __init__(self):
+        self.remotes: dict[Any, Any] = {}
+        
+    
+    def remote_on_build(self, ctx: AnnotationBuildCtx):
+        anot: Annotation = ctx.annotation
+        adornee = anot.adornee
+        assert isinstance(adornee, LuaMethod)
+
+        class_name = REMOTE_INSTANCE_MAP[ctx.annotation.args_val[0]]
+        module_name = adornee.module.returned_name
+
+        anot.export_data["remote_name"] = adornee.name
+        anot.export_data["remote_parent"] = module_name
+
+        self.remotes.setdefault(module_name, {"ClassName": "Folder", "Children": {}})
+        self.remotes[module_name]["Children"][adornee.name] = {"ClassName": class_name}
+
+
+    def on_post_process(self, ctx: PostProcessCtx):
+        #Convert dict to valid .model.json format
+        root_children = []
+
+        for module_name, module_data in self.remotes.items():
+            module_children_map = module_data.get("Children", {})
+            module_children = []
+
+            for remote_name, remote_data in module_children_map.items():
+                module_children.append({
+                    "Name": remote_name,
+                    "ClassName": remote_data["ClassName"],
+                })
+
+            root_children.append({
+                "Name": module_name,
+                "ClassName": "Folder",
+                "Children": module_children,
+            })
+
+        model = {
+            "ClassName": "Folder",
+            "Children": root_children,
+        }
+
+        ctx.dump_json("shared", "Remotes.model.json", model)
+
+
+    def load(self, ctx: ExtensionRegistry):
+        ctx.register_anot(
+            AnnotationDef('remote', scope='method', retention='init', args=[str], on_build=self.remote_on_build)
+        )

lua_annotations/init_project.py

@@ -0,0 +1,197 @@
+import importlib
+from pathlib import Path
+import shutil
+import sys
+import time
+from datetime import datetime
+
+from .api.annotations import ENVIRONMENTS, ExtensionRegistry
+from .build_process import BuildCtxList, BuildProcessCtx, Config, Environment, Extension, PostProcessCtx, Workspace, get_template
+from .exceptions import BuildError, ConfigError
+from .extensions import default as default_ext
+
+WATCH_FILENAMES = ('*.lua', '*.luau')
+
+def create_config(workdir: Path, config_file: Path):
+    if not config_file.exists():
+        default_config = get_template('annotations.config.json')
+        config_file.write_text(default_config)
+        print('Created a default config file')
+    else:
+        print('Config file already exists. Skipping')
+
+
+def iter_rel_paths(path_map: dict[str, str], workdir: Path, env: Environment):
+    for path, lua_expr in path_map.items():
+        if '@' in path:
+            p, lua_expr = process_tags(path, lua_expr, env, workdir)
+        else:
+            p = workdir / Path(path)
+
+        if not p.is_dir():
+            print(f'WARNING: directory {p.as_posix()} does not exist')
+            continue
+
+        yield p, lua_expr
+
+
+def import_extension_from_path(workdir: Path, entry: str):
+    workdir = workdir.resolve()
+    p = (workdir / entry).resolve()
+
+    if str(workdir) not in sys.path:
+        sys.path.insert(0, str(workdir))
+        importlib.invalidate_caches()
+
+    mod_name = '.'.join(p.relative_to(workdir).with_suffix('').parts)
+    return importlib.import_module(mod_name)
+
+
+def import_extension(ext: Extension, workdir: Path):
+    entry_type, entry = ext
+
+    if entry_type == 'library':
+        return importlib.import_module("lua_annotations.extensions.game_framework.main")
+    return import_extension_from_path(workdir, entry)
+
+
+def process_tags(raw: str, raw_expr: str, env: Environment, workdir: Path):
+    name, data = raw.split('@')
+
+    if name == 'wally':
+        package_dir_name = 'Packages' if env == 'shared' else 'ServerPackages'
+        packages = workdir / package_dir_name / '_Index'
+        ext_dir = next(packages.glob(f'*_{data}@*'), None)
+        if not ext_dir:
+            raise ConfigError(
+                f'wally package {data} not found under {packages.as_posix()}'
+            )
+
+        return ext_dir / data, f'require({raw_expr}.{data})' 
+
+    raise ConfigError(f'invalid path tag: {raw}')
+
+
+def build(workdir: Path, config: Config):
+    init_time = datetime.now()
+
+    for raw_workspace in config.workspaces:
+        #process workspace
+        workspace: Workspace = {}
+        for env in ENVIRONMENTS:
+            path_map = raw_workspace.get(env)
+            if not path_map:
+                raise ConfigError(f'path for the `{env}` environment is not defined in the config.')
+
+            rel_paths = dict(iter_rel_paths(path_map, workdir, env))
+            workspace[env] = rel_paths
+
+
+        #load extensions
+        reg = ExtensionRegistry()
+        default_ext.load(reg)
+
+        for ext in config.extensions:
+            #py_entry
+            module = import_extension(ext, workdir)
+            load_fn = getattr(module, 'load')
+
+            if not callable(load_fn):
+                raise BuildError(f'module {ext[1]} does not have a `load()` function')
+            load_fn(reg)
+
+
+        reg = reg.sort_extensions()
+        print(f'loaded {len(reg.anot_registry)} annotations')
+
+
+        #env processing
+        build_contexts: BuildCtxList = {}
+
+        for env in ENVIRONMENTS:
+            path_map = workspace.get(env)
+            if not path_map:
+                raise ConfigError(f'path for the `{env}` environment is not defined in the config.')
+
+            #process output root
+            rel_paths = workspace[env]
+            root_path = next(iter(rel_paths.keys()))
+            output_root = root_path / Path(config.out_dir_name)
+
+            shutil.rmtree(output_root, True)
+            output_root.mkdir(parents=True, exist_ok=True)
+
+            #create and use a ctx
+            ctx = BuildProcessCtx(reg, root_path, workspace, rel_paths, output_root, env)
+            for path in rel_paths:
+                ctx.process_dir(path)
+
+            build_contexts[env] = ctx
+
+
+        # run post-build hooks
+        if build_contexts:
+            ctx = PostProcessCtx(reg, workdir, workspace, build_contexts)
+            for hook in reg.post_build_hooks:
+                hook(ctx)
+
+    #logging
+    delta = datetime.now() - init_time
+    print(f'Built in {delta.total_seconds()}s')
+
+
+#builds a fingerprint of all the last modified times of files
+def _watch_fingerprint(workdir: Path, config_file: Path, config: Config):
+    output_dir_name = config.out_dir_name
+
+    #track config file
+    tracked: dict[str, int] = {str(config_file): config_file.stat().st_mtime_ns}
+
+    #track workspaces
+    for workspace in config.workspaces:
+        for env in ENVIRONMENTS:
+            path_map = workspace.get(env)
+            if not path_map:
+                continue
+
+            for rel_path in path_map:
+                env_workdir = workdir / rel_path
+                if not env_workdir.exists() or not env_workdir.is_dir():
+                    continue
+
+                for pattern in WATCH_FILENAMES:
+                    for file in env_workdir.rglob(pattern):
+                        if output_dir_name in file.parts:
+                            continue
+                        tracked[str(file)] = file.stat().st_mtime_ns
+
+    return tuple(sorted(tracked.items()))
+
+
+def watch(workdir: Path, config_file: Path, poll_interval: float = 1.0):
+    print('Running initial build...')
+    config = read_config(config_file)
+    build(workdir, config)
+
+    last_fingerprint = _watch_fingerprint(workdir, config_file, config)
+    print(f'Watching for changes in {workdir} (interval: {poll_interval}s). Press Ctrl+C to stop.')
+
+    #poll fingerprints every `poll_interval` seconds
+    while True:
+        time.sleep(poll_interval)
+
+        config = read_config(config_file)
+        fingerprint = _watch_fingerprint(workdir, config_file, config)
+
+        if fingerprint != last_fingerprint:
+            print('Change detected, rebuilding...')
+            build(workdir, config)
+            last_fingerprint = fingerprint
+
+
+def read_config(config_file: Path):
+    import json
+
+    if not config_file.exists():
+        raise ConfigError('Config file not found. Run the program in init mode to create one!')
+    return Config(json.loads(config_file.read_text()))

lua_annotations/main.py

@@ -0,0 +1,59 @@
+import argparse
+from pathlib import Path
+import sys
+from typing import Literal
+
+from .exceptions import LuaAnnotationsError
+from .init_project import build, create_config, read_config, watch
+
+
+def main():
+    parser = argparse.ArgumentParser(prog='lua-anot')
+    parser.add_argument('mode', help='mode of the program', choices=['build', 'init', 'watch'])
+    parser.add_argument(
+        'workdir',
+        nargs='?',
+        default='',
+        help='working directory for the program; this should be your rojo project root',
+    )
+    parser.add_argument('-c', '--config', default='annotations.config.json', help='filename of the config file to use')
+    parser.add_argument(
+        '--watch-interval',
+        type=float,
+        default=1.0,
+        help='polling interval in seconds when mode is watch',
+    )
+    args = parser.parse_args()
+
+    mode: Literal['build', 'init', 'watch'] = args.mode
+
+    workdir: Path = Path.cwd() / args.workdir
+    if not workdir.exists() or not workdir.is_dir():
+        raise LuaAnnotationsError(f'Invalid workdir: {workdir}. Provide a valid project directory.')
+
+    config_file: Path = workdir / args.config
+
+    #init mode
+    if mode == 'init':
+        create_config(workdir, config_file)
+        return
+
+    #main mode
+    if mode == 'build':
+        build(workdir, read_config(config_file))
+        return
+
+    #watch mode
+    watch(workdir, config_file, poll_interval=args.watch_interval)
+
+    return 0
+
+
+if __name__ == '__main__':
+    try:
+        main()
+    except KeyboardInterrupt:
+        print('\nStopped watching.')
+    except LuaAnnotationsError as exc:
+        print(f'Error: {exc}')
+        sys.exit(1)

lua_annotations/parser.py

@@ -0,0 +1,277 @@
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from .api.annotations import AnnotationBuildCtx, AnnotationDef, ExtensionRegistry, SortedRegistry
+from .parser_schemas import *
+
+if TYPE_CHECKING:
+    from build_process import BuildProcessCtx
+
+#helper functions
+K = TypeVar('K')
+V = TypeVar('V')
+def reverse_dict(d: dict[K, V]) -> dict[V, K]:
+    return {v: k for k, v in d.items()}
+
+def set_adornee(anots: list[Annotation], adornee: Adornee):
+    for anot in anots:
+        anot.adornee = adornee
+
+def remove_whitespace(t: list[Any]):
+    return [p.strip() for p in t]
+
+def map_param_list(params: list[str]):    
+    out: dict[str, str] = {}
+    for param in params:
+        parts = remove_whitespace(param.split(':'))
+        if len(parts) > 1:
+            out[parts[0]] = parts[1]
+        else:
+            out[parts[0]] = 'any'
+
+    return out
+
+#parsing
+@dataclass
+class FileParser():
+    reg: SortedRegistry
+    file: Path
+    build_ctx: 'BuildProcessCtx'
+    annotations: list[Annotation] = field(default_factory=list)
+    cur_annotations: list[Annotation] = field(default_factory=list)
+    modules: dict[str, LuaModule] = field(default_factory=dict)
+    types: dict[str, LuaType] = field(default_factory=dict)
+    cur_line = 0
+
+    def __post_init__(self):
+        self.file_name = self.file.name.split('.')[0]
+
+    #assertion functions
+    def _check_anot_scopes(self, line: str, anots: list[AnnotationDef]):
+        scope = anots[0].scope
+        for anot in anots:
+            if not anot.scope == scope:
+                self.error(line, f'all annotations must have scope: `{scope}`')
+
+    def _check_anot_relations(self, line: str, anots: list[AnnotationDef]):
+        for anot in anots:
+            for inc in anot.mutual_exclude:
+                if inc in anots:
+                    self.error(line, f'annotation {anot.name} excludes {inc.name}, but it is present in this code block')
+
+            for inc in anot.mutual_include:
+                if not inc in anots:
+                    self.error(line, f'annotation {anot.name} requires {inc.name}, but it is not present in this code block')
+
+
+    #parsing helpers
+    def _parse_anot_args(self, adef: AnnotationDef, args: list[str]):
+        kwargs_val: dict[str, Any] = {}
+        args_val: list[Any] = []
+
+        for i, arg in enumerate(args):
+            if '=' in arg:
+                name, val = [part.strip() for part in arg.split('=', 1)]
+                proc = adef.kwargs[name]
+                kwargs_val[name] = proc(val)
+            else:
+                proc = adef.args[i]
+                args_val.append(proc(arg))
+
+        return args_val, kwargs_val
+
+    def _parse_annotation(self, text: str, ctx: ExtensionRegistry):
+        parts = remove_whitespace(ANNOTATION_ARG_RE.split(text.removeprefix(ANNOTATION_PREFIX)))
+        name = parts[0]
+
+        adef = ctx.anot_registry.get(name)
+        if adef:
+            args, kwargs = self._parse_anot_args(adef, parts[1:])
+            return Annotation(adef, name, args, kwargs)
+        else:
+            self.error(text, 'Annotation does not exist')
+
+    def _get_dict_data(self, text: str):
+        matches = DICT_REGEX.findall(text)
+        if not len(matches) > 0:
+            self.error(text, 'line is not a dict')
+
+        keys: list[str] = [m[0] for m in matches]
+        values: list[str] = [m[1] for m in matches]
+            
+        if len(keys) == len(values):
+            out: dict[str, str] = {}
+            for i, key in enumerate(keys):
+                out[key] = values[i].strip().removesuffix('}').strip()
+
+            return out
+
+    def _get_returned(self, text: str, default_name: str):
+        match = RETURN_REGEX.search(text)
+        if not match:
+            return
+
+        single: str = match.group(2)
+
+        if single:
+            return ReturnDefinition(default_name, 'single', single_module=single)
+        else:
+            tablestr: str = match.group(1)
+            if not tablestr:
+                self.error(text, 'module export is incorrectly defined')
+
+            dict_data = self._get_dict_data(tablestr)
+            if dict_data:
+                return ReturnDefinition(default_name, 'dict', dict_val=reverse_dict(dict_data))
+            else:
+                self.error(text, 'module export is not a table')
+
+    def _get_returned_value(self, text: str, returned: ReturnDefinition):
+        match = VARIABLE_REGEX.search(text)
+        if not match:
+            self.error(text, 'code block is not a variable declaration')
+
+        name: str = match.group(1)
+        returned_name, is_submodule = returned.get_returned_name(name)
+
+        if not (name and returned_name):
+            self.error(text, 'invalid returned value definition or it is not exported.')
+
+        return ReturnedValue(self.file, name, returned_name, is_submodule)
+
+
+    def _get_function(self, text: str, modules: dict[str, LuaModule]):
+        match = FUNCTION_REGEX.search(text)
+        if not match:
+            self.error(text, 'function is incorrectly defined')
+
+        module_name: str = match.group(1)
+        fun_name: str = match.group(2)
+        raw_params: str = match.group(3)
+        return_type: str = match.group(4) or 'any'
+
+        if not (module_name or fun_name):
+            self.error(text, 'method is incorrectly defined')
+
+        if not raw_params.strip() == '':
+            params = remove_whitespace(raw_params.split(','))
+            param_dict = map_param_list(params)
+        else:
+            param_dict = {}
+
+        if not module_name in modules:
+            self.error(module_name, 'cannot use method annotations for an unindexed module.')
+        return LuaMethod(fun_name, modules[module_name], param_dict, return_type)
+
+
+    #main functions
+    def error(self, text: str, message: str):
+        raise LuaParserError(message, text, self.cur_line, self.file_name)
+
+    def parse(self, text: str):        
+        returned = self._get_returned(text, self.file_name)
+        if not returned:
+            print(f'Skipping file {self.file_name}; doesn\'t return a value')
+            return
+        lines = [l.rstrip() for l in text.splitlines()]
+
+        for i, line in enumerate(lines):
+            self.cur_line += 1
+            #skip empty lines
+            if line == '':
+                continue
+        
+            #comments
+            elif line.startswith('--'):
+                #annotation
+                if line.startswith(ANNOTATION_PREFIX):
+                    anot = self._parse_annotation(line, self.reg)
+                    if anot:
+                        self.cur_annotations.append(anot)
+                    else:
+                        self.error(line, 'Not an annotation')
+
+            else:
+                #if there are annotations in this block of code, then find adornee
+                if len(self.cur_annotations) > 0:
+                    adefs = [anot.adef for anot in self.cur_annotations]
+
+                    self._check_anot_relations(line, adefs)
+                    self._check_anot_scopes(line, adefs)
+
+                    scope = adefs[0].scope
+
+                    #strip comments
+                    line = line.split('--')[0]
+                    
+                    #methods
+                    if scope == 'method':
+                        method = self._get_function(line, self.modules)
+                        set_adornee(self.cur_annotations, method)
+
+                    #module
+                    elif scope == 'module':
+                        match = MODULE_REGEX.search(line)
+                        if not match:
+                            self.error(line, 'code block is not a module')
+                        
+                        name: str = match.group(1)
+                        returned_name, is_submodule = returned.get_returned_name(name)
+
+                        if not (name and returned_name):
+                            self.error(line, 'invalid module definition or it is not returned.')
+
+                        module = LuaModule(self.file, name, returned_name, is_submodule)
+                        set_adornee(self.cur_annotations, module)
+                        self.modules[module.name] = module
+
+
+                    #returned value
+                    elif scope == 'returned_value':
+                        returned_value = self._get_returned_value(line, returned)
+                        set_adornee(self.cur_annotations, returned_value)
+
+
+                    #type
+                    elif scope == 'type':
+                        #get entire code block
+                        block = ''
+                        for line2 in lines[i:]:
+                            block += line2 + '\n'
+                            if '}' in line2:
+                                break
+
+                        #use type regex
+                        match = TYPE_REGEX.search(block)
+                        if not match:
+                            self.error(line, 'code block is not a type definition')
+
+                        exported = bool(match.group(1))
+                        name: str = match.group(2)
+                        contents: str = match.group(3)
+
+                        if not (name and contents):
+                            self.error(line, 'type definition is missing name or contents')
+
+                        if contents.startswith('{'):
+                            data = self._get_dict_data(contents)
+                        else:
+                            data = contents
+
+                        if not data:
+                            self.error(line, 'type definition is missing type data')
+
+                        lua_type = LuaType(name, data, exported)
+
+                        set_adornee(self.cur_annotations, lua_type)
+                        self.types[name] = lua_type
+
+                    #now run anot on_build
+                    for anot in self.cur_annotations:
+                        for adef in [anot.adef] + anot.adef.extends:
+                            if adef.on_build:
+                                adef.on_build(AnnotationBuildCtx(anot, self, self.build_ctx))
+
+                    self.annotations += self.cur_annotations
+                    self.cur_annotations = []