pyxle-langkit 0.2.0__py3-none-any.whl

pyxle_langkit/__init__.py

@@ -0,0 +1,18 @@
+"""Pyxle language toolkit: LSP server, linter, and editor integrations.
+
+Public API for consumers that need to parse, analyze, or index ``.pyx``
+files programmatically.
+"""
+
+from __future__ import annotations
+
+from .document import PyxDocument
+from .parser_adapter import TolerantParser
+from .workspace import WorkspaceIndex, WorkspaceSymbol
+
+__all__ = [
+    "PyxDocument",
+    "TolerantParser",
+    "WorkspaceIndex",
+    "WorkspaceSymbol",
+]

pyxle_langkit/cli.py

@@ -0,0 +1,206 @@
+"""Command-line interface for Pyxle language tools.
+
+Provides ``parse``, ``lint``, ``outline``, and ``format`` subcommands
+for use outside of an editor.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from pathlib import Path
+
+import typer
+
+from .linter import PyxLinter
+from .parser_adapter import TolerantParser
+from .symbols import extract_document_symbols
+
+app = typer.Typer(
+    name="pyxle-langkit",
+    help="Language tools for Pyxle .pyx files.",
+    no_args_is_help=True,
+)
+
+
+# ------------------------------------------------------------------
+# parse
+# ------------------------------------------------------------------
+
+
+@app.command()
+def parse(
+    file: Path = typer.Argument(..., exists=True, help="Path to a .pyx file."),
+) -> None:
+    """Parse a .pyx file and output its structure as JSON."""
+    parser = TolerantParser()
+    document = parser.parse(file)
+
+    output = {
+        "path": str(document.path),
+        "has_python": document.has_python,
+        "has_jsx": document.has_jsx,
+        "python_lines": len(document.python_code.splitlines()),
+        "jsx_lines": len(document.jsx_code.splitlines()),
+        "loader": (
+            {
+                "name": document.loader.name,
+                "line": document.loader.line_number,
+                "is_async": document.loader.is_async,
+                "parameters": list(document.loader.parameters),
+            }
+            if document.loader
+            else None
+        ),
+        "actions": [
+            {
+                "name": a.name,
+                "line": a.line_number,
+                "is_async": a.is_async,
+                "parameters": list(a.parameters),
+            }
+            for a in document.actions
+        ],
+        "head_elements": list(document.head_elements),
+        "head_is_dynamic": document.head_is_dynamic,
+        "diagnostics": [
+            {
+                "section": d.section,
+                "severity": d.severity,
+                "message": d.message,
+                "line": d.line,
+            }
+            for d in document.diagnostics
+        ],
+    }
+
+    typer.echo(json.dumps(output, indent=2))
+
+
+# ------------------------------------------------------------------
+# lint
+# ------------------------------------------------------------------
+
+
+@app.command()
+def lint(
+    file: Path = typer.Argument(..., exists=True, help="Path to a .pyx file."),
+) -> None:
+    """Lint a .pyx file and print diagnostics."""
+    parser = TolerantParser()
+    document = parser.parse(file)
+    linter = PyxLinter()
+    issues = linter.lint(document)
+
+    # Also include parser diagnostics.
+    has_errors = False
+
+    for diag in document.diagnostics:
+        severity = diag.severity.upper()
+        line = diag.line or "?"
+        color = typer.colors.RED if diag.severity == "error" else typer.colors.YELLOW
+        typer.secho(
+            f"  {line:>5}  {severity:<8}  [{diag.section}] {diag.message}",
+            fg=color,
+        )
+        if diag.severity == "error":
+            has_errors = True
+
+    for issue in issues:
+        severity = issue.severity.upper()
+        color = (
+            typer.colors.RED
+            if issue.severity == "error"
+            else typer.colors.YELLOW
+            if issue.severity == "warning"
+            else typer.colors.CYAN
+        )
+        typer.secho(
+            f"  {issue.line:>5}  {severity:<8}  [{issue.rule}] {issue.message}",
+            fg=color,
+        )
+        if issue.severity == "error":
+            has_errors = True
+
+    total = len(issues) + len(document.diagnostics)
+    if total == 0:
+        typer.secho("  No issues found.", fg=typer.colors.GREEN)
+    else:
+        typer.echo(f"\n  {total} issue(s) found.")
+
+    if has_errors:
+        raise typer.Exit(code=1)
+
+
+# ------------------------------------------------------------------
+# outline
+# ------------------------------------------------------------------
+
+
+@app.command()
+def outline(
+    file: Path = typer.Argument(..., exists=True, help="Path to a .pyx file."),
+) -> None:
+    """Show the symbol outline of a .pyx file."""
+    parser = TolerantParser()
+    document = parser.parse(file)
+    symbols = extract_document_symbols(document)
+
+    if not symbols:
+        typer.echo("  (no symbols)")
+        return
+
+    for sym in symbols:
+        detail = f"  ({sym.detail})" if sym.detail else ""
+        typer.echo(f"  {sym.line:>5}  {sym.kind:<16}  {sym.name}{detail}")
+
+
+# ------------------------------------------------------------------
+# format
+# ------------------------------------------------------------------
+
+
+@app.command(name="format")
+def format_cmd(
+    file: Path = typer.Argument(..., exists=True, help="Path to a .pyx file."),
+    python_formatter: str = typer.Option("ruff", help="Python formatter: ruff, black, none."),
+    jsx_formatter: str = typer.Option("prettier", help="JSX formatter: prettier, none."),
+    check: bool = typer.Option(False, "--check", help="Check if file would be changed."),
+) -> None:
+    """Format a .pyx file."""
+    from .formatting import format_document
+
+    text = file.read_text(encoding="utf-8")
+    edits = asyncio.run(
+        format_document(
+            text,
+            path=file,
+            python_formatter=python_formatter,
+            jsx_formatter=jsx_formatter,
+        )
+    )
+
+    if not edits:
+        typer.echo(f"  {file}: already formatted")
+        return
+
+    if check:
+        typer.secho(f"  {file}: would be reformatted", fg=typer.colors.YELLOW)
+        raise typer.Exit(code=1)
+
+    # Apply edits to the original text.
+    lines = text.splitlines(keepends=True)
+    # Apply edits in reverse order so line numbers stay valid.
+    for edit in sorted(edits, key=lambda e: e.start_line, reverse=True):
+        start_idx = edit.start_line - 1
+        end_idx = edit.end_line - 1
+        new_lines = (edit.new_text + "\n").splitlines(keepends=True)
+        lines[start_idx:end_idx] = new_lines
+
+    formatted = "".join(lines)
+    file.write_text(formatted, encoding="utf-8")
+    typer.secho(f"  {file}: reformatted", fg=typer.colors.GREEN)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    app()

pyxle_langkit/completions.py

@@ -0,0 +1,397 @@
+"""Completion provider for ``.pyx`` files.
+
+Combines Jedi-based Python completions with Pyxle-specific component
+and import completions for JSX sections.
+"""
+
+from __future__ import annotations
+
+import ast
+import logging
+import re
+from dataclasses import dataclass
+from typing import Sequence
+
+from lsprotocol.types import (
+    CompletionItem,
+    CompletionItemKind,
+    InsertTextFormat,
+    MarkupContent,
+    MarkupKind,
+)
+
+from pyxle_langkit.document import PyxDocument
+
+logger = logging.getLogger(__name__)
+
+# ------------------------------------------------------------------
+# Safe jedi import
+# ------------------------------------------------------------------
+
+try:
+    import jedi
+except ImportError:
+    jedi = None  # type: ignore[assignment]
+
+# ------------------------------------------------------------------
+# Pyxle component definitions
+# ------------------------------------------------------------------
+
+
+@dataclass(frozen=True, slots=True)
+class _ComponentDef:
+    """Definition of a built-in Pyxle component for completion."""
+
+    name: str
+    props: tuple[str, ...]
+    doc: str
+    is_container: bool = False
+
+
+_PYXLE_COMPONENTS: tuple[_ComponentDef, ...] = (
+    _ComponentDef(
+        name="Link",
+        props=("href", "prefetch", "replace", "scroll"),
+        doc="Client-side navigation link. Prefetches on hover by default.",
+    ),
+    _ComponentDef(
+        name="Script",
+        props=("src", "strategy", "async", "defer", "module", "noModule"),
+        doc="Managed script tag with loading strategy control.",
+    ),
+    _ComponentDef(
+        name="Image",
+        props=("src", "width", "height", "alt", "priority", "lazy"),
+        doc="Optimised image component with automatic sizing.",
+    ),
+    _ComponentDef(
+        name="Head",
+        props=(),
+        doc="Container for ``<head>`` meta elements.",
+        is_container=True,
+    ),
+    _ComponentDef(
+        name="Slot",
+        props=("name",),
+        doc="Named slot for layout composition.",
+    ),
+    _ComponentDef(
+        name="ClientOnly",
+        props=(),
+        doc="Renders children only on the client (skipped during SSR).",
+        is_container=True,
+    ),
+    _ComponentDef(
+        name="Form",
+        props=("action", "method"),
+        doc="Enhanced form with server action integration.",
+    ),
+)
+
+_PYXLE_COMPONENT_NAMES = frozenset(c.name for c in _PYXLE_COMPONENTS)
+_PYXLE_COMPONENT_MAP = {c.name: c for c in _PYXLE_COMPONENTS}
+
+_IMPORT_SOURCE = "pyxle/client"
+
+# ------------------------------------------------------------------
+# Tag context detection
+# ------------------------------------------------------------------
+
+_TAG_OPEN_RE = re.compile(r"<\s*([A-Z]\w*)?$")
+_PROP_CONTEXT_RE = re.compile(r"<\s*([A-Z]\w+)\b[^>]*\s+(\w*)$")
+_DATA_DOT_RE = re.compile(r"\bdata\.(\w*)$")
+_IMPORT_RE = re.compile(
+    r"""import\s*\{[^}]*$|from\s+['"]pyxle/client['"]\s*$""",
+)
+
+# ------------------------------------------------------------------
+# Jedi completion kind mapping
+# ------------------------------------------------------------------
+
+_JEDI_KIND_MAP: dict[str, CompletionItemKind] = {
+    "module": CompletionItemKind.Module,
+    "class": CompletionItemKind.Class,
+    "instance": CompletionItemKind.Variable,
+    "function": CompletionItemKind.Function,
+    "param": CompletionItemKind.Variable,
+    "path": CompletionItemKind.File,
+    "keyword": CompletionItemKind.Keyword,
+    "property": CompletionItemKind.Property,
+    "statement": CompletionItemKind.Variable,
+}
+
+
+# ------------------------------------------------------------------
+# Completion provider
+# ------------------------------------------------------------------
+
+
+class CompletionProvider:
+    """Provides completions for Python and JSX sections of ``.pyx`` files."""
+
+    def complete(
+        self,
+        document: PyxDocument,
+        line: int,
+        column: int,
+    ) -> Sequence[CompletionItem]:
+        """Provide completions at the given position in a ``.pyx`` file.
+
+        *line* is 1-indexed (matches LSP convention after +1 adjustment).
+        *column* is 0-indexed.
+        """
+        section = document.section_at_line(line)
+
+        if section == "python":
+            return self._complete_python(document, line, column)
+        if section == "jsx":
+            return self._complete_jsx(document, line, column)
+
+        return ()
+
+    # ------------------------------------------------------------------
+    # Python completions (via jedi)
+    # ------------------------------------------------------------------
+
+    def _complete_python(
+        self,
+        document: PyxDocument,
+        line: int,
+        column: int,
+    ) -> Sequence[CompletionItem]:
+        """Provide Python completions using Jedi."""
+        if jedi is None:
+            logger.debug("Jedi not available; skipping Python completions")
+            return ()
+
+        virtual_code, line_numbers = document.virtual_python_for_jedi()
+        if not virtual_code.strip():
+            return ()
+
+        virtual_line = _map_to_virtual_line(line, line_numbers)
+        if virtual_line is None:
+            return ()
+
+        path = str(document.path) if document.path else None
+        try:
+            script = jedi.Script(virtual_code, path=path)
+            completions = script.complete(virtual_line, column)
+        except Exception:
+            logger.debug("Jedi completion failed", exc_info=True)
+            return ()
+
+        return tuple(
+            _jedi_completion_to_lsp(c) for c in completions
+        )
+
+    # ------------------------------------------------------------------
+    # JSX completions (Pyxle-specific)
+    # ------------------------------------------------------------------
+
+    def _complete_jsx(
+        self,
+        document: PyxDocument,
+        line: int,
+        column: int,
+    ) -> Sequence[CompletionItem]:
+        """Provide JSX completions for Pyxle components, props, and data."""
+        # Get the current line text from JSX source.
+        line_text = _get_jsx_line_text(document, line)
+        if line_text is None:
+            return ()
+
+        prefix = line_text[:column] if column <= len(line_text) else line_text
+        items: list[CompletionItem] = []
+
+        # 1. Component tag completions (after '<').
+        tag_match = _TAG_OPEN_RE.search(prefix)
+        if tag_match is not None:
+            items.extend(self._complete_components(tag_match.group(1) or ""))
+            return tuple(items)
+
+        # 2. Prop completions (inside an open tag).
+        prop_match = _PROP_CONTEXT_RE.search(prefix)
+        if prop_match is not None:
+            component_name = prop_match.group(1)
+            prop_prefix = prop_match.group(2)
+            items.extend(self._complete_props(component_name, prop_prefix))
+            return tuple(items)
+
+        # 3. data.{key} completions.
+        data_match = _DATA_DOT_RE.search(prefix)
+        if data_match is not None:
+            items.extend(self._complete_data_keys(document, data_match.group(1)))
+            return tuple(items)
+
+        # 4. Import completions.
+        if _IMPORT_RE.search(prefix):
+            items.extend(self._complete_imports(""))
+            return tuple(items)
+
+        return tuple(items)
+
+    def _complete_components(self, prefix: str) -> Sequence[CompletionItem]:
+        """Provide Pyxle component name completions."""
+        items: list[CompletionItem] = []
+        for comp in _PYXLE_COMPONENTS:
+            if comp.name.startswith(prefix):
+                snippet = (
+                    f"{comp.name}>${{0}}</{comp.name}>"
+                    if comp.is_container
+                    else f"{comp.name} ${{0}}/>"
+                )
+                items.append(
+                    CompletionItem(
+                        label=comp.name,
+                        kind=CompletionItemKind.Class,
+                        detail=f"pyxle/client — {comp.doc}",
+                        insert_text=snippet,
+                        insert_text_format=InsertTextFormat.Snippet,
+                    )
+                )
+        return items
+
+    def _complete_props(
+        self,
+        component_name: str,
+        prop_prefix: str,
+    ) -> Sequence[CompletionItem]:
+        """Provide prop completions for a Pyxle component."""
+        comp = _PYXLE_COMPONENT_MAP.get(component_name)
+        if comp is None:
+            return ()
+
+        items: list[CompletionItem] = []
+        for prop in comp.props:
+            if prop.startswith(prop_prefix):
+                items.append(
+                    CompletionItem(
+                        label=prop,
+                        kind=CompletionItemKind.Property,
+                        detail=f"{component_name} prop",
+                        insert_text=f'{prop}={{${{0}}}}',
+                        insert_text_format=InsertTextFormat.Snippet,
+                    )
+                )
+        return items
+
+    def _complete_data_keys(
+        self,
+        document: PyxDocument,
+        prefix: str,
+    ) -> Sequence[CompletionItem]:
+        """Provide ``data.{key}`` completions from the loader return dict."""
+        keys = _infer_loader_return_keys(document)
+        items: list[CompletionItem] = []
+        for key in keys:
+            if key.startswith(prefix):
+                items.append(
+                    CompletionItem(
+                        label=key,
+                        kind=CompletionItemKind.Property,
+                        detail="loader data",
+                    )
+                )
+        return items
+
+    def _complete_imports(self, prefix: str) -> Sequence[CompletionItem]:
+        """Provide import completions for ``pyxle/client``."""
+        items: list[CompletionItem] = []
+        for name in sorted(_PYXLE_COMPONENT_NAMES):
+            if name.startswith(prefix):
+                items.append(
+                    CompletionItem(
+                        label=name,
+                        kind=CompletionItemKind.Class,
+                        detail=f"import from {_IMPORT_SOURCE}",
+                    )
+                )
+        return items
+
+
+# ------------------------------------------------------------------
+# Helpers
+# ------------------------------------------------------------------
+
+
+def _map_to_virtual_line(
+    pyx_line: int,
+    virtual_line_numbers: tuple[int, ...],
+) -> int | None:
+    """Map a 1-indexed .pyx line to a 1-indexed virtual Python line.
+
+    Searches the line map for the first entry matching *pyx_line*.
+    Returns ``None`` if no mapping exists.
+    """
+    for virtual_idx, orig_line in enumerate(virtual_line_numbers):
+        if orig_line == pyx_line:
+            return virtual_idx + 1
+    return None
+
+
+def _get_jsx_line_text(document: PyxDocument, pyx_line: int) -> str | None:
+    """Get the text of a JSX line corresponding to a .pyx line number.
+
+    Returns ``None`` if the line is not in the JSX section.
+    """
+    jsx_lines = document.jsx_code.splitlines()
+    for jsx_idx, orig_line in enumerate(document.jsx_line_numbers):
+        if orig_line == pyx_line and jsx_idx < len(jsx_lines):
+            return jsx_lines[jsx_idx]
+    return None
+
+
+def _jedi_completion_to_lsp(completion: object) -> CompletionItem:
+    """Convert a Jedi completion to an LSP ``CompletionItem``."""
+    name = getattr(completion, "name", "")
+    type_str = getattr(completion, "type", "")
+    description = getattr(completion, "description", "")
+
+    kind = _JEDI_KIND_MAP.get(type_str, CompletionItemKind.Text)
+
+    doc: MarkupContent | None = None
+    if description:
+        doc = MarkupContent(kind=MarkupKind.PlainText, value=description)
+
+    return CompletionItem(
+        label=name,
+        kind=kind,
+        detail=type_str,
+        documentation=doc,
+    )
+
+
+def _infer_loader_return_keys(document: PyxDocument) -> tuple[str, ...]:
+    """Infer the dict keys returned by the ``@server`` loader function.
+
+    Parses the Python AST looking for the loader function and inspects
+    its return statement(s). If the return value is a dict literal,
+    extracts the string keys.
+    """
+    if document.loader is None or not document.has_python:
+        return ()
+
+    try:
+        tree = ast.parse(document.python_code)
+    except SyntaxError:
+        return ()
+
+    loader_name = document.loader.name
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            if node.name == loader_name:
+                return _extract_return_dict_keys(node)
+
+    return ()
+
+
+def _extract_return_dict_keys(func_node: ast.FunctionDef | ast.AsyncFunctionDef) -> tuple[str, ...]:
+    """Extract string keys from dict return statements in a function."""
+    keys: list[str] = []
+    for node in ast.walk(func_node):
+        if isinstance(node, ast.Return) and node.value is not None:
+            if isinstance(node.value, ast.Dict):
+                for key in node.value.keys:
+                    if isinstance(key, ast.Constant) and isinstance(key.value, str):
+                        keys.append(key.value)
+    return tuple(dict.fromkeys(keys))  # Deduplicate, preserve order.