renpy-language-server 0.2.0__py3-none-any.whl

renpy_language_server/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__: str = version("renpy-language-server")
+except PackageNotFoundError:  # running from a source checkout without installing
+    __version__ = "0.0.0.dev0"

renpy_language_server/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m renpy_language_server``."""
+
+from renpy_language_server.cli import main
+
+raise SystemExit(main())

renpy_language_server/analysis.py

@@ -0,0 +1,230 @@
+"""Logical lines and the block tree shared by server features.
+
+The scanner already knows where a physical line continues an earlier logical
+line. This module turns that information into two small structures:
+
+* :class:`LogicalLine` - one Ren'Py statement, possibly spanning several
+  physical lines;
+* :class:`Block` - a colon-terminated statement with its indented body.
+
+It is deliberately not a parser. It is accurate enough for symbols, navigation,
+diagnostics and fold ranges, and it never treats the inside of a string or a
+bracket continuation as a block opener.
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Literal
+
+from .scanner import State, scan_line
+
+_TAB = 4
+_FIRST_TOKEN = re.compile(r"\S+")
+
+LineKind = Literal["code", "comment", "blank", "continuation"]
+
+
+@dataclass(frozen=True)
+class LogicalLine:
+    """One Ren'Py statement, from its first to its last physical line."""
+
+    text: str
+    start_line: int
+    end_line: int
+    indent: int
+    depth: int
+    kind: LineKind
+    first_word: str
+    opens_block: bool
+
+
+def _no_children() -> "list[Block]":
+    return []
+
+
+@dataclass
+class Block:
+    """A colon-terminated statement and its indented body."""
+
+    line: LogicalLine
+    parent: "Block | None"
+    children: "list[Block]" = field(default_factory=_no_children)
+    end_line: int = 0
+
+
+@dataclass
+class Analysis:
+    """Result of analysing one source file."""
+
+    lines: list[LogicalLine]
+    blocks: list[Block]
+    indent_unit: int
+
+    def line_at(self, line: int) -> LogicalLine | None:
+        """Return the logical line containing physical ``line``."""
+        for item in self.lines:
+            if item.start_line <= line <= item.end_line:
+                return item
+        return None
+
+    def block_at(self, line: int) -> Block | None:
+        """Return the innermost block whose range contains ``line``."""
+        found: Block | None = None
+        for block in self.blocks:
+            if block.line.start_line <= line <= block.end_line and (
+                found is None or block.line.start_line >= found.line.start_line
+            ):
+                found = block
+        return found
+
+    def enclosing_label(self, line: int) -> Block | None:
+        """Return the closest ``label`` block containing ``line``."""
+        block = self.block_at(line)
+        while block is not None:
+            if block.line.first_word == "label":
+                return block
+            block = block.parent
+        return None
+
+
+@dataclass
+class _Pending:
+    start_line: int
+    end_line: int
+    text: str
+    indent: int
+    kind: LineKind
+    first_word: str
+    last_char: str
+
+
+def analyze(source: str, *, default_indent: int = 4) -> Analysis:
+    """Analyse ``source`` into logical lines and a block tree."""
+    raw_lines = _split_lines(source)
+    pending = _collect_logical_lines(raw_lines)
+    indent_unit = _infer_indent_unit(pending, default_indent)
+
+    stack: list[Block] = []
+    blocks: list[Block] = []
+    lines: list[LogicalLine] = []
+
+    for item in pending:
+        if item.kind != "blank":
+            while stack and item.indent <= stack[-1].line.indent:
+                _close_block(stack.pop())
+
+        line = LogicalLine(
+            text=item.text,
+            start_line=item.start_line,
+            end_line=item.end_line,
+            indent=item.indent,
+            depth=len(stack),
+            kind=item.kind,
+            first_word=item.first_word,
+            opens_block=item.kind != "comment" and item.last_char == ":",
+        )
+        lines.append(line)
+
+        if item.kind != "blank":
+            for block in stack:
+                block.end_line = item.end_line
+
+        if line.opens_block:
+            parent = stack[-1] if stack else None
+            block = Block(line=line, parent=parent, end_line=line.end_line)
+            blocks.append(block)
+            if parent is not None:
+                parent.children.append(block)
+            stack.append(block)
+
+    while stack:
+        _close_block(stack.pop())
+
+    return Analysis(lines=lines, blocks=blocks, indent_unit=indent_unit)
+
+
+def _close_block(block: Block) -> None:
+    block.end_line = max(block.end_line, block.line.end_line)
+
+
+def _split_lines(source: str) -> list[str]:
+    text = source.replace("\r\n", "\n").replace("\r", "\n")
+    return text.split("\n")
+
+
+def _collect_logical_lines(raw_lines: list[str]) -> list[_Pending]:
+    state = State()
+    pending: list[_Pending] = []
+    current: _Pending | None = None
+
+    for index, raw in enumerate(raw_lines):
+        info = scan_line(raw, state)
+        stripped = raw.strip()
+
+        if state.clean:
+            if current is not None:
+                pending.append(current)
+                current = None
+
+            if stripped:
+                text = stripped
+                current = _Pending(
+                    start_line=index,
+                    end_line=index,
+                    text=text,
+                    indent=_leading_width(raw),
+                    kind="comment" if text.startswith("#") else "code",
+                    first_word=_first_word(text),
+                    last_char=info.last_char,
+                )
+            else:
+                pending.append(
+                    _Pending(
+                        start_line=index,
+                        end_line=index,
+                        text="",
+                        indent=0,
+                        kind="blank",
+                        first_word="",
+                        last_char="",
+                    )
+                )
+        elif current is not None:
+            current.end_line = index
+            if info.last_char:
+                current.last_char = info.last_char
+        else:
+            # A continuation without a logical-line opener should not happen
+            # with a balanced scanner. Keep it as a safe code line.
+            current = _Pending(
+                start_line=index,
+                end_line=index,
+                text=stripped,
+                indent=_leading_width(raw),
+                kind="continuation",
+                first_word=_first_word(stripped),
+                last_char=info.last_char,
+            )
+
+        state = info.end
+
+    if current is not None:
+        pending.append(current)
+    return pending
+
+
+def _infer_indent_unit(lines: list[_Pending], default_indent: int) -> int:
+    for line in lines:
+        if line.kind == "code" and line.indent > 0:
+            return line.indent
+    return default_indent if default_indent > 0 else _TAB
+
+
+def _first_word(text: str) -> str:
+    match = _FIRST_TOKEN.match(text)
+    return match.group(0) if match else ""
+
+
+def _leading_width(line: str) -> int:
+    stripped = line.lstrip(" \t")
+    return len(line[: len(line) - len(stripped)].expandtabs(_TAB))

renpy_language_server/assets.py

@@ -0,0 +1,104 @@
+"""Automatic image and audio assets from the project folders."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+AssetKind = Literal["image", "audio"]
+
+IMAGE_SUFFIXES = frozenset({".png", ".jpg", ".jpeg", ".webp", ".avif"})
+AUDIO_SUFFIXES = frozenset({".ogg", ".opus", ".mp3", ".wav", ".mp2"})
+MAX_ASSETS = 20_000
+
+
+@dataclass(frozen=True)
+class Asset:
+    """One file that Ren'Py treats as an image or audio resource."""
+
+    kind: AssetKind
+    name: str
+    path: Path
+
+
+class AssetIndex:
+    """A cached map of asset names to files."""
+
+    def __init__(self) -> None:
+        self._images: dict[str, Asset] = {}
+        self._audio: dict[str, Asset] = {}
+
+    def scan(self, roots: list[Path]) -> None:
+        """Replace the index with assets found under ``roots``."""
+        images: dict[str, Asset] = {}
+        audio: dict[str, Asset] = {}
+
+        for root in _unique_dirs(roots):
+            if len(images) + len(audio) >= MAX_ASSETS:
+                break
+            for directory in (root / "game" / "images", root / "images"):
+                if directory.is_dir():
+                    _scan_directory(directory, "image", IMAGE_SUFFIXES, images)
+            for directory in (root / "game" / "audio", root / "audio"):
+                if directory.is_dir():
+                    _scan_directory(directory, "audio", AUDIO_SUFFIXES, audio)
+
+        self._images = images
+        self._audio = audio
+
+    def images(self) -> list[Asset]:
+        return list(self._images.values())
+
+    def audio(self) -> list[Asset]:
+        return list(self._audio.values())
+
+    def find_image(self, name: str) -> Asset | None:
+        return self._images.get(name)
+
+    def find_audio(self, name: str) -> Asset | None:
+        direct = self._audio.get(name)
+        if direct is not None:
+            return direct
+        if not name.startswith("audio/"):
+            return self._audio.get(f"audio/{name}")
+        return None
+
+
+def _unique_dirs(roots: list[Path]) -> list[Path]:
+    result: list[Path] = []
+    seen: set[Path] = set()
+    for root in roots:
+        resolved = root.resolve()
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        result.append(resolved)
+    return result
+
+
+def _scan_directory(
+    directory: Path,
+    kind: AssetKind,
+    suffixes: frozenset[str],
+    target: dict[str, Asset],
+) -> None:
+    for path in sorted(directory.rglob("*")):
+        if len(target) >= MAX_ASSETS:
+            return
+        if not path.is_file() or path.suffix.lower() not in suffixes:
+            continue
+        try:
+            relative = path.relative_to(directory)
+        except ValueError:
+            continue
+        if any(part.startswith(".") for part in relative.parts):
+            continue
+        if kind == "image":
+            name = _image_name(relative)
+        else:
+            name = f"audio/{relative.as_posix()}"
+        target.setdefault(name, Asset(kind=kind, name=name, path=path))
+
+
+def _image_name(relative: Path) -> str:
+    parts = list(relative.with_suffix("").parts)
+    return " ".join(part.replace("_", " ") for part in parts)

renpy_language_server/builtins.py

@@ -0,0 +1,54 @@
+"""Bundled Ren'Py API documentation.
+
+The data is generated from the MIT-licensed ``renpy.json`` shipped by
+``renpy/vscode-language-renpy``. See ``NOTICE.md`` for attribution.
+"""
+
+import json
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib.resources import files
+
+
+@dataclass(frozen=True)
+class Builtin:
+    """One Ren'Py function, class, action or variable."""
+
+    name: str
+    kind: str
+    args: str
+    type: str
+    category: str
+    documentation: str
+
+    @property
+    def signature(self) -> str:
+        return f"{self.name}{self.args}" if self.args else self.name
+
+
+@lru_cache(maxsize=1)
+def builtins() -> dict[str, Builtin]:
+    """Load and cache the bundled API table."""
+    path = files("renpy_language_server.data").joinpath("renpy_api.json")
+    raw = json.loads(path.read_text(encoding="utf-8"))
+    result: dict[str, Builtin] = {}
+    for name, value in raw.items():
+        result[name] = Builtin(
+            name=name,
+            kind=value["kind"],
+            args=value["args"],
+            type=value["type"],
+            category=value["category"],
+            documentation=value["doc"],
+        )
+    return result
+
+
+def lookup(name: str) -> Builtin | None:
+    """Return the built-in with exactly ``name``, if it exists."""
+    return builtins().get(name)
+
+
+def iter_builtins() -> tuple[Builtin, ...]:
+    """Return every bundled built-in in a stable order."""
+    return tuple(builtins().values())

renpy_language_server/cli.py

@@ -0,0 +1,190 @@
+"""Command line entry point.
+
+``renpy-language-server``                 start the language server on stdio
+``renpy-language-server dap``             start the launch-only debug adapter on stdio
+``renpy-language-server format FILE...``  format files in place (``--check``, ``--diff``)
+"""
+
+import difflib
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from . import __version__
+from .formatter import FormatOptions, format_source
+
+app = typer.Typer(
+    name="renpy-language-server",
+    help="Ren'Py language server.",
+    invoke_without_command=True,
+    no_args_is_help=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        print(f"renpy-language-server {__version__}")
+        raise typer.Exit
+
+
+@app.callback()
+def root(
+    ctx: typer.Context,
+    *,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show version and exit.",
+        ),
+    ] = False,
+    stdio: Annotated[
+        bool,
+        typer.Option("--stdio", help="Accepted for client compatibility."),
+    ] = False,
+) -> None:
+    """Start the language server on stdio (default when no subcommand is given)."""
+    _ = (version, stdio)
+    if ctx.invoked_subcommand is None:
+        from .server import run  # imported lazily: the CLI should start fast
+
+        run()
+
+
+def _iter_files(paths: list[str]) -> list[Path]:
+    files: list[Path] = []
+    for raw in paths:
+        path = Path(raw)
+        if path.is_dir():
+            files.extend(sorted(path.rglob("*.rpy")))
+            files.extend(sorted(path.rglob("*.rpym")))
+        else:
+            files.append(path)
+    return files
+
+
+def _format_impl(
+    paths: list[str],
+    *,
+    check: bool,
+    diff: bool,
+    indent: int,
+    spacing: bool,
+    quotes: bool,
+    python_format: bool,
+) -> int:
+    options = FormatOptions(
+        indent=indent,
+        normalize_spacing=spacing,
+        normalize_quotes=quotes,
+        format_python=python_format,
+    )
+
+    if paths == ["-"]:
+        _ = sys.stdout.write(format_source(sys.stdin.read(), options))
+        return 0
+
+    changed = 0
+    for path in _iter_files(paths):
+        with open(path, encoding="utf-8", newline="") as fh:
+            old = fh.read()
+        new = format_source(old, options)
+        if old == new:
+            continue
+        changed += 1
+        if diff:
+            _ = sys.stdout.writelines(
+                difflib.unified_diff(
+                    old.splitlines(keepends=True),
+                    new.splitlines(keepends=True),
+                    fromfile=str(path),
+                    tofile=str(path),
+                )
+            )
+        elif check:
+            print(f"would reformat {path}", file=sys.stderr)
+        else:
+            with open(path, "w", encoding="utf-8", newline="") as fh:
+                _ = fh.write(new)
+            print(f"reformatted {path}", file=sys.stderr)
+
+    return 1 if changed and (check or diff) else 0
+
+
+@app.command()
+def dap() -> None:
+    """Start the launch-only Debug Adapter Protocol server on stdio."""
+    from .dap import run  # imported lazily: the CLI should start fast
+
+    raise typer.Exit(run())
+
+
+@app.command()
+def format(
+    paths: Annotated[
+        list[str],
+        typer.Argument(help="Files or directories; '-' reads stdin."),
+    ],
+    *,
+    check: Annotated[
+        bool,
+        typer.Option("--check", help="Exit 1 if any file would change."),
+    ] = False,
+    diff: Annotated[
+        bool,
+        typer.Option("--diff", help="Print a diff instead of writing."),
+    ] = False,
+    indent: Annotated[
+        int,
+        typer.Option("--indent", help="Spaces per indentation level."),
+    ] = 4,
+    spacing: Annotated[
+        bool,
+        typer.Option(
+            "--spacing/--no-spacing",
+            help="Normalize spacing around operators in Python statements.",
+        ),
+    ] = True,
+    python_format: Annotated[
+        bool,
+        typer.Option(
+            "--python/--no-python",
+            help="Format python: blocks with Ruff (not whitespace-only).",
+        ),
+    ] = False,
+    quotes: Annotated[
+        bool,
+        typer.Option(
+            "--quotes/--no-quotes",
+            help="Rewrite single-quoted strings to double quotes.",
+        ),
+    ] = True,
+) -> None:
+    """Format .rpy files."""
+    rc = _format_impl(
+        paths,
+        check=check,
+        diff=diff,
+        indent=indent,
+        spacing=spacing,
+        quotes=quotes,
+        python_format=python_format,
+    )
+    raise typer.Exit(rc)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for programmatic use and tests.
+
+    Returns the process exit code (0 = success).
+    When no subcommand is given the language server is started.
+    """
+    try:
+        app(args=argv, standalone_mode=True)
+    except SystemExit as exc:
+        return int(exc.code or 0)
+    return 0