avrae-ls 0.6.0__py3-none-any.whl → 0.6.2__py3-none-any.whl

avrae_ls/server.py

@@ -0,0 +1,447 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+import ast
+from typing import Any, Dict
+from importlib import metadata
+
+import draconic
+from lsprotocol import types
+from pygls import uris
+from pygls.lsp.server import LanguageServer
+
+from .config import AvraeLSConfig, load_config
+from .context import ContextBuilder
+from .diagnostics import DiagnosticProvider
+from .runtime import MockExecutor
+from .alias_preview import render_alias_command, simulate_command
+from .parser import find_draconic_blocks
+from .signature_help import load_signatures, signature_help_for_code
+from .completions import gather_suggestions, completion_items_for_position, hover_for_position
+from .code_actions import code_actions_for_document
+from .symbols import build_symbol_table, document_symbols, find_definition_range, find_references, range_for_word
+from .argument_parsing import apply_argument_parsing
+
+# Prefer package metadata so the server version matches the installed wheel.
+try:
+    __version__ = metadata.version("avrae-ls")
+except metadata.PackageNotFoundError:
+    __version__ = "0.0.0+unknown"
+log = logging.getLogger(__name__)
+
+RUN_ALIAS_COMMAND = "avrae.runAlias"
+REFRESH_CONFIG_COMMAND = "avrae.reloadConfig"
+REFRESH_GVARS_COMMAND = "avrae.refreshGvars"
+LEVEL_TO_SEVERITY = {
+    "error": types.DiagnosticSeverity.Error,
+    "warning": types.DiagnosticSeverity.Warning,
+    "info": types.DiagnosticSeverity.Information,
+}
+
+
+@dataclass
+class ServerState:
+    config: AvraeLSConfig
+    context_builder: ContextBuilder
+    diagnostics: DiagnosticProvider
+    executor: MockExecutor
+    warnings: list[str] = field(default_factory=list)
+
+
+class AvraeLanguageServer(LanguageServer):
+    def __init__(self):
+        super().__init__(
+            name="avrae-ls",
+            version=__version__,
+            text_document_sync_kind=types.TextDocumentSyncKind.Incremental,
+        )
+        self._state: ServerState | None = None
+        self._workspace_root: Path | None = None
+        self._signatures: Dict[str, Any] = load_signatures()
+
+    @property
+    def state(self) -> ServerState:
+        if self._state is None:
+            raise RuntimeError("Server has not been initialized")
+        return self._state
+
+    @property
+    def workspace_root(self) -> Path:
+        if self._workspace_root is None:
+            return Path.cwd()
+        return self._workspace_root
+
+    def load_workspace(self, root: Path) -> None:
+        config, warnings = load_config(root)
+        executor = MockExecutor(config.service)
+        context_builder = ContextBuilder(config)
+        diagnostics = DiagnosticProvider(executor, config.diagnostics)
+        self._state = ServerState(
+            config=config,
+            context_builder=context_builder,
+            diagnostics=diagnostics,
+            executor=executor,
+            warnings=list(warnings),
+        )
+        self._workspace_root = root
+        log.info("Loaded workspace at %s", root)
+
+
+ls = AvraeLanguageServer()
+
+
+@ls.feature(types.INITIALIZE)
+def on_initialize(server: AvraeLanguageServer, params: types.InitializeParams):
+    root_uri = params.root_uri or (params.workspace_folders[0].uri if params.workspace_folders else None)
+    root_path = Path(uris.to_fs_path(root_uri)) if root_uri else Path.cwd()
+    server.load_workspace(root_path)
+
+
+@ls.feature(types.INITIALIZED)
+async def on_initialized(server: AvraeLanguageServer, params: types.InitializedParams):
+    for warning in server.state.warnings:
+        server.window_log_message(
+            types.LogMessageParams(type=types.MessageType.Warning, message=warning)
+        )
+
+
+@ls.feature(types.TEXT_DOCUMENT_DID_OPEN)
+async def did_open(server: AvraeLanguageServer, params: types.DidOpenTextDocumentParams):
+    await _publish_diagnostics(server, params.text_document.uri)
+
+
+@ls.feature(types.TEXT_DOCUMENT_DID_CHANGE)
+async def did_change(server: AvraeLanguageServer, params: types.DidChangeTextDocumentParams):
+    await _publish_diagnostics(server, params.text_document.uri)
+
+
+@ls.feature(types.TEXT_DOCUMENT_DID_SAVE)
+async def did_save(server: AvraeLanguageServer, params: types.DidSaveTextDocumentParams):
+    await _publish_diagnostics(server, params.text_document.uri)
+
+
+@ls.feature(types.WORKSPACE_DID_CHANGE_CONFIGURATION)
+async def did_change_config(server: AvraeLanguageServer, params: types.DidChangeConfigurationParams):
+    server.load_workspace(server.workspace_root)
+    for warning in server.state.warnings:
+        server.window_log_message(
+            types.LogMessageParams(type=types.MessageType.Warning, message=warning)
+        )
+
+
+@ls.feature(types.TEXT_DOCUMENT_DOCUMENT_SYMBOL)
+def on_document_symbol(server: AvraeLanguageServer, params: types.DocumentSymbolParams):
+    doc = server.workspace.get_text_document(params.text_document.uri)
+    symbols = document_symbols(doc.source)
+    return symbols
+
+
+@ls.feature(types.TEXT_DOCUMENT_DEFINITION)
+def on_definition(server: AvraeLanguageServer, params: types.DefinitionParams):
+    doc = server.workspace.get_text_document(params.text_document.uri)
+    table = build_symbol_table(doc.source)
+    word = doc.word_at_position(params.position)
+    rng = find_definition_range(table, word)
+    if rng is None:
+        return None
+    return types.Location(uri=params.text_document.uri, range=rng)
+
+
+@ls.feature(types.TEXT_DOCUMENT_REFERENCES)
+def on_references(server: AvraeLanguageServer, params: types.ReferenceParams):
+    doc = server.workspace.get_text_document(params.text_document.uri)
+    table = build_symbol_table(doc.source)
+    word = doc.word_at_position(params.position)
+    if not word or not table.lookup(word):
+        return []
+
+    ranges = find_references(table, doc.source, word, include_declaration=params.context.include_declaration)
+    return [types.Location(uri=params.text_document.uri, range=rng) for rng in ranges]
+
+
+@ls.feature(types.TEXT_DOCUMENT_PREPARE_RENAME)
+def on_prepare_rename(server: AvraeLanguageServer, params: types.PrepareRenameParams):
+    doc = server.workspace.get_text_document(params.text_document.uri)
+    table = build_symbol_table(doc.source)
+    word = doc.word_at_position(params.position)
+    if not word or not table.lookup(word):
+        return None
+    return range_for_word(doc.source, params.position)
+
+
+@ls.feature(types.TEXT_DOCUMENT_RENAME)
+def on_rename(server: AvraeLanguageServer, params: types.RenameParams):
+    doc = server.workspace.get_text_document(params.text_document.uri)
+    table = build_symbol_table(doc.source)
+    word = doc.word_at_position(params.position)
+    if not word or not table.lookup(word) or not params.new_name:
+        return None
+
+    ranges = find_references(table, doc.source, word, include_declaration=True)
+    if not ranges:
+        return None
+    edits = [types.TextEdit(range=rng, new_text=params.new_name) for rng in ranges]
+    return types.WorkspaceEdit(changes={params.text_document.uri: edits})
+
+
+@ls.feature(types.WORKSPACE_SYMBOL)
+def on_workspace_symbol(server: AvraeLanguageServer, params: types.WorkspaceSymbolParams):
+    symbols: list[types.SymbolInformation] = []
+    query = (params.query or "").lower()
+    for uri, doc in server.workspace.text_documents.items():
+        table = build_symbol_table(doc.source)
+        for entry in table.entries:
+            if query and query not in entry.name.lower():
+                continue
+            symbols.append(
+                types.SymbolInformation(
+                    name=entry.name,
+                    kind=entry.kind,
+                    location=types.Location(uri=uri, range=entry.range),
+                )
+            )
+    return symbols
+
+
+@ls.feature(types.TEXT_DOCUMENT_SIGNATURE_HELP)
+def on_signature_help(server: AvraeLanguageServer, params: types.SignatureHelpParams):
+    doc = server.workspace.get_text_document(params.text_document.uri)
+    source = apply_argument_parsing(doc.source)
+    blocks = find_draconic_blocks(source)
+    pos = params.position
+    if not blocks:
+        return signature_help_for_code(source, pos.line, pos.character, server._signatures)
+
+    for block in blocks:
+        start = block.line_offset
+        end = block.line_offset + block.line_count
+        if start <= pos.line <= end:
+            rel_line = pos.line - start
+            help_ = signature_help_for_code(block.code, rel_line, pos.character, server._signatures)
+            if help_:
+                return help_
+    return None
+
+
+@ls.feature(
+    types.TEXT_DOCUMENT_COMPLETION,
+    types.CompletionOptions(trigger_characters=["."]),
+)
+def on_completion(server: AvraeLanguageServer, params: types.CompletionParams):
+    doc = server.workspace.get_text_document(params.text_document.uri)
+    ctx_data = server.state.context_builder.build()
+    suggestions = gather_suggestions(ctx_data, server.state.context_builder.gvar_resolver, server._signatures)
+    source = apply_argument_parsing(doc.source)
+    blocks = find_draconic_blocks(source)
+    pos = params.position
+    if not blocks:
+        return completion_items_for_position(source, pos.line, pos.character, suggestions)
+
+    for block in blocks:
+        start = block.line_offset
+        end = block.line_offset + block.line_count
+        if start <= pos.line <= end:
+            rel_line = pos.line - start
+            return completion_items_for_position(block.code, rel_line, pos.character, suggestions)
+    return []
+
+
+@ls.feature(types.TEXT_DOCUMENT_HOVER)
+def on_hover(server: AvraeLanguageServer, params: types.HoverParams):
+    doc = server.workspace.get_text_document(params.text_document.uri)
+    ctx_data = server.state.context_builder.build()
+    pos = params.position
+    source = apply_argument_parsing(doc.source)
+    blocks = find_draconic_blocks(source)
+    if not blocks:
+        return hover_for_position(source, pos.line, pos.character, server._signatures, ctx_data, server.state.context_builder.gvar_resolver)
+
+    for block in blocks:
+        start = block.line_offset
+        end = block.line_offset + block.line_count
+        if start <= pos.line <= end:
+            rel_line = pos.line - start
+            return hover_for_position(block.code, rel_line, pos.character, server._signatures, ctx_data, server.state.context_builder.gvar_resolver)
+    return None
+
+
+@ls.feature(types.TEXT_DOCUMENT_CODE_ACTION)
+def on_code_action(server: AvraeLanguageServer, params: types.CodeActionParams):
+    doc = server.workspace.get_text_document(params.text_document.uri)
+    return code_actions_for_document(doc.source, params, server.workspace_root)
+
+
+@ls.command(RUN_ALIAS_COMMAND)
+async def run_alias(server: AvraeLanguageServer, *args: Any):
+    payload = args[0] if args else {}
+    uri = None
+    text = None
+    profile = None
+    alias_args: list[str] | None = None
+    doc = None
+    if isinstance(payload, dict):
+        uri = payload.get("uri")
+        text = payload.get("text")
+        profile = payload.get("profile")
+        if isinstance(payload.get("args"), list):
+            alias_args = [str(a) for a in payload["args"]]
+
+    if text is None and uri:
+        doc = server.workspace.get_text_document(uri)
+        text = doc.source
+
+    if text is None:
+        return {"error": "No alias content supplied"}
+
+    ctx_data = server.state.context_builder.build(profile)
+    rendered = await render_alias_command(
+        text,
+        server.state.executor,
+        ctx_data,
+        server.state.context_builder.gvar_resolver,
+        args=alias_args,
+    )
+    preview = simulate_command(rendered.command)
+
+    response: dict[str, Any] = {
+        "stdout": rendered.stdout,
+        "result": preview.preview if preview.preview is not None else rendered.last_value,
+        "command": rendered.command,
+        "commandName": preview.command_name,
+    }
+    if rendered.error:
+        response["error"] = _format_runtime_error(rendered.error)
+    if preview.validation_error:
+        response["validationError"] = preview.validation_error
+    if preview.embed:
+        response["embed"] = preview.embed.to_dict()
+    response["state"] = {
+        "character": ctx_data.character,
+        "combat": ctx_data.combat,
+        "vars": {
+            "cvars": dict(ctx_data.vars.cvars),
+            "uvars": dict(ctx_data.vars.uvars),
+            "svars": dict(ctx_data.vars.svars),
+            "gvars": dict(ctx_data.vars.gvars),
+        },
+    }
+    if uri:
+        extra = []
+        if rendered.error:
+            src = doc.source if doc else text
+            extra.append(
+                _runtime_diagnostic_with_source(
+                    rendered.error, server.state.config.diagnostics.runtime_level, src
+                )
+            )
+        await _publish_diagnostics(server, uri, profile=profile, extra=extra)
+    return response
+
+
+@ls.command(REFRESH_GVARS_COMMAND)
+async def refresh_gvars(server: AvraeLanguageServer, *args: Any):
+    payload = args[0] if args else {}
+    profile = None
+    keys: list[str] | None = None
+    if isinstance(payload, dict):
+        profile = payload.get("profile")
+        raw_keys = payload.get("keys")
+        if isinstance(raw_keys, list):
+            keys = [str(k) for k in raw_keys]
+
+    ctx_data = server.state.context_builder.build(profile)
+    resolver = server.state.context_builder.gvar_resolver
+    snapshot = await resolver.refresh(ctx_data.vars.gvars, keys)
+    return {"count": len(snapshot), "gvars": snapshot}
+
+
+@ls.command(REFRESH_CONFIG_COMMAND)
+def reload_config(server: AvraeLanguageServer, *args: Any):
+    server.load_workspace(server.workspace_root)
+    return {"status": "ok"}
+
+
+async def _publish_diagnostics(
+    server: AvraeLanguageServer,
+    uri: str,
+    profile: str | None = None,
+    extra: list[types.Diagnostic] | None = None,
+) -> None:
+    doc = server.workspace.get_text_document(uri)
+    ctx_data = server.state.context_builder.build(profile)
+    diags = await server.state.diagnostics.analyze(
+        doc.source, ctx_data, server.state.context_builder.gvar_resolver
+    )
+    if extra:
+        diags.extend(extra)
+    server.text_document_publish_diagnostics(
+        types.PublishDiagnosticsParams(uri=uri, diagnostics=diags, version=doc.version)
+    )
+
+
+def _format_runtime_error(error: BaseException) -> str:
+    if isinstance(error, draconic.DraconicException):
+        return error.msg
+    return str(error)
+
+
+def _runtime_diagnostic(error: BaseException, level: str) -> types.Diagnostic:
+    return _runtime_diagnostic_with_source(error, level, None)
+
+
+def _runtime_diagnostic_with_source(error: BaseException, level: str, source: str | None) -> types.Diagnostic:
+    severity = LEVEL_TO_SEVERITY.get(level.lower(), types.DiagnosticSeverity.Error)
+    if source and hasattr(error, "module"):
+        rng = _find_using_range(source, getattr(error, "module", None))
+        if rng:
+            return types.Diagnostic(message=str(error), range=rng, severity=severity, source="avrae-ls-runtime")
+    if isinstance(error, draconic.DraconicSyntaxError):
+        rng = types.Range(
+            start=types.Position(line=max((error.lineno or 1) - 1, 0), character=max((error.offset or 1) - 1, 0)),
+            end=types.Position(
+                line=max(((error.end_lineno or error.lineno or 1) - 1), 0),
+                character=max(((error.end_offset or error.offset or 1) - 1), 0),
+            ),
+        )
+        message = error.msg
+    elif hasattr(error, "node"):
+        node = getattr(error, "node")
+        rng = types.Range(
+            start=types.Position(line=max(getattr(node, "lineno", 1) - 1, 0), character=max(getattr(node, "col_offset", 0), 0)),
+            end=types.Position(
+                line=max(getattr(node, "end_lineno", getattr(node, "lineno", 1)) - 1, 0),
+                character=max(getattr(node, "end_col_offset", getattr(node, "col_offset", 0) + 1), 0),
+            ),
+        )
+        message = getattr(error, "msg", str(error))
+    else:
+        rng = types.Range(
+            start=types.Position(line=0, character=0),
+            end=types.Position(line=0, character=1),
+        )
+        message = str(error)
+    return types.Diagnostic(message=message, range=rng, severity=severity, source="avrae-ls-runtime")
+
+
+def _find_using_range(source: str, module: str | None) -> types.Range | None:
+    if not module:
+        return None
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return None
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id == "using":
+            for kw in node.keywords:
+                if kw.arg and isinstance(kw.value, ast.Constant) and isinstance(kw.value.value, str):
+                    if kw.value.value == module:
+                        start = types.Position(line=node.lineno - 1, character=node.col_offset)
+                        end = types.Position(line=node.end_lineno - 1, character=node.end_col_offset)
+                        return types.Range(start=start, end=end)
+    return None
+
+
+def create_server() -> AvraeLanguageServer:
+    return ls

avrae_ls/signature_help.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+import ast
+import inspect
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from lsprotocol import types
+
+from .runtime import _default_builtins
+
+
+@dataclass
+class FunctionSig:
+    name: str
+    params: List[str]
+    doc: str = ""
+
+    @property
+    def label(self) -> str:
+        params = ", ".join(self.params)
+        return f"{self.name}({params})"
+
+
+def load_signatures() -> Dict[str, FunctionSig]:
+    sigs: dict[str, FunctionSig] = {}
+    sigs.update(_builtin_sigs())
+    sigs.update(_runtime_helper_sigs())
+    sigs.update(_avrae_function_sigs())
+    return sigs
+
+
+def _builtin_sigs() -> Dict[str, FunctionSig]:
+    sigs: dict[str, FunctionSig] = {}
+    for name, fn in _default_builtins().items():
+        try:
+            sig = inspect.signature(fn)
+        except (TypeError, ValueError):
+            continue
+        params = [p.name for p in sig.parameters.values()]
+        sigs[name] = FunctionSig(name=name, params=params, doc=fn.__doc__ or "")
+    return sigs
+
+
+def _runtime_helper_sigs() -> Dict[str, FunctionSig]:
+    helpers = {
+        "get_gvar": (
+            ["address"],
+            "Retrieves and returns the value of a global variable (gvar) by address.",
+        ),
+        "get_svar": (
+            ["name", "default=None"],
+            "Gets a server variable by name, returning default if it is not present.",
+        ),
+        "get_uvar": (
+            ["name", "default=None"],
+            "Gets a user variable by name as a string, returning default if it is not present.",
+        ),
+        "get_uvars": (
+            [],
+            "Returns the mapping of user variables available to the caller (values are strings).",
+        ),
+        "set_uvar": (
+            ["name", "value"],
+            "Sets a user variable (stored as a string) and returns the stored value.",
+        ),
+        "set_uvar_nx": (
+            ["name", "value"],
+            "Sets a user variable only if it does not already exist; returns the stored string value.",
+        ),
+        "delete_uvar": (
+            ["name"],
+            "Deletes a user variable and returns its previous value or None if missing.",
+        ),
+        "uvar_exists": (
+            ["name"],
+            "Returns whether a user variable is set.",
+        ),
+        "exists": (
+            ["name"],
+            "Returns whether a name is set in the current evaluation context.",
+        ),
+        "get": (
+            ["name", "default=None"],
+            "Gets the value of a name using local > cvar > uvar resolution order; returns default if not set.",
+        ),
+        "using": (
+            ["**imports"],
+            "Imports one or more gvars as modules into the current namespace with the provided aliases.",
+        ),
+        "signature": (
+            ["data=0"],
+            "Generates a signed invocation signature encoding invocation context and optional 5-bit user data.",
+        ),
+        "verify_signature": (
+            ["data"],
+            "Verifies a signature generated by signature(); returns context data or raises ValueError when invalid.",
+        ),
+        "print": (
+            ["*values"],
+            "Writes values to alias output using the configured separator/end (mirrors Python print).",
+        ),
+        "character": (
+            [],
+            "Returns the active character object for this alias, or raises if none is available.",
+        ),
+        "combat": (
+            [],
+            "Returns the current combat context if one exists, otherwise None.",
+        ),
+        "argparse": (
+            ["args", "character=None", "splitter=argsplit", "parse_ephem=True"],
+            "Parses alias arguments using Avrae's argparse helper.",
+        ),
+    }
+    return {name: FunctionSig(name=name, params=params, doc=doc) for name, (params, doc) in helpers.items()}
+
+
+def _avrae_function_sigs() -> Dict[str, FunctionSig]:
+    sigs: dict[str, FunctionSig] = {}
+    module_path = Path(__file__).resolve().parent.parent / "avrae" / "aliasing" / "api" / "functions.py"
+    if not module_path.exists():
+        return sigs
+    try:
+        tree = ast.parse(module_path.read_text())
+    except Exception:
+        return sigs
+
+    for node in tree.body:
+        if isinstance(node, ast.FunctionDef) and not node.name.startswith("_"):
+            params: list[str] = []
+            defaults = list(node.args.defaults)
+            default_offset = len(node.args.args) - len(defaults)
+            for idx, arg in enumerate(node.args.args):
+                default_val = None
+                if idx >= default_offset:
+                    default_node = defaults[idx - default_offset]
+                    try:
+                        default_val = ast.literal_eval(default_node)
+                    except Exception:
+                        default_val = None
+                params.append(f"{arg.arg}={default_val}" if default_val is not None else arg.arg)
+            doc = ast.get_docstring(node) or ""
+            sigs[node.name] = FunctionSig(name=node.name, params=params, doc=doc)
+    return sigs
+
+
+def signature_help_for_code(code: str, line: int, character: int, sigs: Dict[str, FunctionSig]) -> Optional[types.SignatureHelp]:
+    try:
+        tree = ast.parse(code)
+    except SyntaxError:
+        return None
+
+    target_call: ast.Call | None = None
+    target_depth = -1
+
+    class Finder(ast.NodeVisitor):
+        def __init__(self):
+            self.stack: list[ast.AST] = []
+
+        def visit_Call(self, node: ast.Call):
+            nonlocal target_call, target_depth
+            if hasattr(node, "lineno") and hasattr(node, "col_offset"):
+                start = (node.lineno - 1, node.col_offset)
+                end_line = getattr(node, "end_lineno", node.lineno) - 1
+                end_col = getattr(node, "end_col_offset", node.col_offset)
+                if _pos_within((line, character), start, (end_line, end_col)):
+                    depth = len(self.stack)
+                    # Prefer the most nested call covering the cursor
+                    if depth >= target_depth:
+                        target_call = node
+                        target_depth = depth
+            self.stack.append(node)
+            self.generic_visit(node)
+            self.stack.pop()
+
+    Finder().visit(tree)
+
+    if not target_call:
+        return None
+
+    if isinstance(target_call.func, ast.Name):
+        name = target_call.func.id
+    else:
+        return None
+
+    if name not in sigs:
+        return None
+
+    fsig = sigs[name]
+    sig_info = types.SignatureInformation(
+        label=fsig.label,
+        documentation=fsig.doc,
+        parameters=[types.ParameterInformation(label=p) for p in fsig.params],
+    )
+    active_param = _active_param_index(target_call, (line, character), fsig.params)
+    return types.SignatureHelp(signatures=[sig_info], active_signature=0, active_parameter=active_param)
+
+
+def _pos_within(pos: Tuple[int, int], start: Tuple[int, int], end: Tuple[int, int]) -> bool:
+    (line, col) = pos
+    (sl, sc) = start
+    (el, ec) = end
+    if line < sl or line > el:
+        return False
+    if line == sl and col < sc:
+        return False
+    if line == el and col > ec:
+        return False
+    return True
+
+
+def _active_param_index(call: ast.Call, cursor: Tuple[int, int], params: List[str]) -> int:
+    if not params:
+        return 0
+
+    # Build spans for positional args and keywords in source order.
+    spans: list[tuple[Tuple[int, int], Tuple[int, int], ast.AST]] = []
+    for arg in call.args:
+        spans.append((_node_start(arg), _node_end(arg), arg))
+    for kw in call.keywords:
+        spans.append((_node_start(kw), _node_end(kw), kw))
+    spans.sort(key=lambda s: (s[0][0], s[0][1]))
+
+    def _clamp(idx: int) -> int:
+        return max(0, min(idx, max(len(params) - 1, 0)))
+
+    for idx, (start, end, node) in enumerate(spans):
+        if _pos_within(cursor, start, end):
+            if isinstance(node, ast.keyword) and node.arg and node.arg in params:
+                return _clamp(params.index(node.arg))
+            return _clamp(idx)
+
+    # If cursor is after some args but not inside one, infer next argument slot.
+    before_count = sum(1 for start, _, _ in spans if start <= cursor)
+    return _clamp(before_count)
+
+
+def _node_start(node: ast.AST) -> Tuple[int, int]:
+    return (getattr(node, "lineno", 1) - 1, getattr(node, "col_offset", 0))
+
+
+def _node_end(node: ast.AST) -> Tuple[int, int]:
+    return (
+        getattr(node, "end_lineno", getattr(node, "lineno", 1)) - 1,
+        getattr(node, "end_col_offset", getattr(node, "col_offset", 0)),
+    )