opencrbasic 1.0.0__py3-none-any.whl

opencrbasic/inlay.py

@@ -0,0 +1,169 @@
+"""Parameter-name inlay hints, independent of any language-server protocol.
+
+A hint is drawn before each positional argument of an instruction or builtin-function call, using
+the parameter names `hover.signature_help` shows. Positions are physical: 0-based line and
+decoded-character column (`docs/lsp-api.md` "Source positions"); the server converts encodings.
+See `docs/lsp-api.md` "Inlay hints (LSP-09a)".
+"""
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import lexer, positions
+from . import syntax as S
+from .hover import declarations, signature_help
+from .navigation import path_keys
+
+_UNITS_STATEMENT = re.compile(r"\s*Units\s+\w", re.I)
+
+__all__ = ["InlayHint", "parameter_hints"]
+
+
+@dataclass(frozen=True)
+class InlayHint:
+    line: int  # 0-based physical line
+    column: int  # decoded-character column of the argument's first character
+    label: str  # `Name:`
+    kind: str = "parameter"
+    padding_right: bool = True
+
+
+class _Frame:
+    __slots__ = ("sig", "index", "first", "last")
+
+    def __init__(self, sig):
+        self.sig = sig  # SignatureInfo of a call frame; None for grouping `(` and `{`
+        self.index = 0
+        self.first = None  # first and last token of the current argument
+        self.last = None
+
+
+def _occurrence_paths(program, result) -> dict[int, Path | None]:
+    paths = {o.id: o.path for o in getattr(program, "occurrences", None) or []}
+    if paths.get(0) is None:
+        paths[0] = Path(result.request.entry).absolute()
+    return paths
+
+
+def _shift(unit, ll, seg: int) -> int | None:
+    """Offset of `unit.text` within `ll.text[seg:]` (a `Units` text is stripped), or None."""
+    tail = ll.text[seg:]
+    for cand in (0, len(tail) - len(tail.lstrip())):
+        if ll.text.startswith(unit.text, seg + cand):
+            return cand
+    return None
+
+
+def parameter_hints(result, path, start_line: int, end_line: int, profile, help_provider=None) -> list[InlayHint]:
+    """Hints for the calls of `path` (a file of the analysis) on physical lines
+    `start_line..end_line`, both 0-based and inclusive, sorted by position.
+
+    A hint needs the call's help names to pair with the catalog positions (`SignatureInfo.paired`),
+    so none appear without a help provider. No hint for an empty argument, for an argument whose
+    text already equals the parameter name (case-insensitive), past the parameter count, or when the
+    argument's first character has no exact single-piece physical position. Never raises."""
+    try:
+        return _hints(result, path, start_line, end_line, profile, help_provider)
+    except Exception:
+        return []
+
+
+def _hints(result, path, start_line, end_line, profile, help_provider) -> list[InlayHint]:
+    program = getattr(result, "program", None)
+    statements = getattr(program, "statements", None)
+    if not statements or help_provider is None:
+        return []
+    keys = path_keys(path)
+    paths = _occurrence_paths(program, result)
+    declared = declarations(program)
+    sigs: dict[tuple[str, bool], object] = {}
+    found: dict[tuple[int, int], InlayHint] = {}
+
+    def signature(name: str, instruction: bool):
+        key = (name.upper(), instruction)
+        if key not in sigs:
+            sig = None if name.upper() in declared else signature_help(name, 0, profile, help_provider)
+            if sig is not None and (sig.kind == "instruction") != instruction:
+                sig = None
+            sigs[key] = sig if sig is not None and sig.paired and sig.parameters else None
+        return sigs[key]
+
+    for stmt in statements:
+        text = getattr(stmt, "text", "")
+        origin = getattr(stmt, "origin", None)
+        if origin is None or "(" not in text or _UNITS_STATEMENT.match(text):
+            continue
+        ll, seg = origin
+        shift = _shift(stmt, ll, seg)
+        if shift is None:
+            continue
+        try:
+            toks = lexer.tokenize(text, stmt.line)
+        except lexer.LexError:
+            continue
+
+        def emit(first, last, frame) -> None:
+            if first is None or frame.index >= len(frame.sig.parameters):
+                return
+            label = frame.sig.parameters[frame.index].label
+            written = text[first.col : last.col + len(last.text)]
+            if written.strip().lower() == label.lower():
+                return
+            start = seg + shift + first.col
+            r = positions.exact_range(ll, start, start + len(first.text))
+            if r is None or r.end_col <= r.start_col or not start_line <= r.line - 1 <= end_line:
+                return
+            p = paths.get(r.occurrence)
+            if p is None or not (path_keys(p) & keys):
+                return
+            found.setdefault((r.line - 1, r.start_col), InlayHint(r.line - 1, r.start_col, label + ":"))
+
+        stack: list[_Frame] = []
+        for i, t in enumerate(toks):
+            if t.kind == "EOF":
+                break
+            top = stack[-1] if stack else None
+            closing = t.kind == "OP" and t.text in (")", "}")
+            comma = t.kind == "OP" and t.text == ","
+            if top is not None and top.sig is not None:
+                if comma:
+                    emit(top.first, top.last, top)
+                    top.index += 1
+                    top.first = top.last = None
+                    continue
+                if closing:
+                    emit(top.first, top.last, top)
+                    stack.pop()
+                    # the closing token belongs to the enclosing argument
+                    if stack and stack[-1].sig is not None:
+                        _extend(stack[-1], t)
+                    continue
+                _extend(top, t)
+            elif closing and top is not None:
+                stack.pop()
+                if stack and stack[-1].sig is not None:
+                    _extend(stack[-1], t)
+                continue
+            if t.kind == "OP" and t.text in ("(", "{"):
+                sig = None
+                if (
+                    t.text == "("
+                    and i
+                    and toks[i - 1].kind == "IDENT"
+                    and not (i > 1 and toks[i - 2].kind == "OP" and toks[i - 2].text == ".")
+                ):
+                    name = toks[i - 1]
+                    first_in_stmt = i == 1 and isinstance(stmt, S.Instruction) and stmt.keyword == name.upper
+                    sig = signature(name.text, first_in_stmt)
+                stack.append(_Frame(sig))
+        for frame in stack:  # an unclosed call ends at the end of the line
+            if frame.sig is not None:
+                emit(frame.first, frame.last, frame)
+    return sorted(found.values(), key=lambda h: (h.line, h.column))
+
+
+def _extend(frame: _Frame, tok) -> None:
+    if frame.first is None:
+        frame.first = tok
+    frame.last = tok

opencrbasic/lexer.py

@@ -0,0 +1,183 @@
+"""Tokenizer for one CRBasic logical line.
+
+`source.py` hands this module already-joined, comment-stripped logical lines (continuation
+lines merged, in-string content untouched). This module never sees raw physical files.
+
+Token kinds: ``IDENT`` (identifier or case-insensitive keyword), ``NUMBER``, ``STRING``,
+``OP`` (operator/punctuation, including compound assignments and ``#``), ``EOF``.
+
+Numbers: decimal integers and floats (with optional exponent), and ``&H..``/``&B..`` integer
+literals. Identifiers: letters, digits, ``_`` (leading ``_`` allowed, e.g. ``_60Hz``), with an
+optional single trailing ``$`` (e.g. ``CHR$``). Strings: ``"..."`` with ``""`` as an escaped
+quote. Every token keeps its original spelling (`text`), an upper-cased form for
+case-insensitive matching (`upper`), and its `col` (0-based offset into the logical line's
+joined text) and `line` (the physical source line supplied by the caller -- see docs/frontend.md
+for why CR6Comp reports the *last* physical line of a continued statement, which is what
+`source.py` assigns as the logical line's `line`).
+"""
+
+import re
+from dataclasses import dataclass
+
+# Longest operators first so the scanner prefers the multi-character spelling.
+_OPERATORS = [
+    "<>",
+    "<=",
+    ">=",
+    "<<",
+    ">>",
+    "+=",
+    "-=",
+    "*=",
+    "/=",
+    "\\=",
+    "^=",
+    "&=",
+    "+",
+    "-",
+    "*",
+    "/",
+    "\\",
+    "^",
+    "&",
+    "=",
+    "<",
+    ">",
+    "(",
+    ")",
+    ",",
+    ".",
+    ":",
+    ";",
+    "{",
+    "}",
+    "#",
+    "!",
+    "@",  # pointer variables: `Type!` declarations, `!x` dereference, `@x` address-of
+]
+# Sort by length desc so the regex alternation tries multi-char spellings first.
+_OPERATORS.sort(key=len, reverse=True)
+_OP_RE = re.compile("|".join(re.escape(op) for op in _OPERATORS))
+
+_IDENT_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\$?")
+_HEX_RE = re.compile(r"&[Hh][0-9A-Fa-f]+")
+_BIN_RE = re.compile(r"&[Bb][01]+")
+# Exponent is optional; the decimal point may lead with no integer part (`.111111`, confirmed
+# valid CRBasic by corpus testing -- addprecise_1.CR6 -- see docs/frontend.md) or have no
+# fractional part at all.
+_NUMBER_RE = re.compile(r"(\d+\.\d*|\.\d+|\d+)([Ee][+-]?\d+)?")
+
+KEYWORD_KINDS = {"IDENT"}
+
+
+@dataclass(frozen=True)
+class Token:
+    kind: str  # "IDENT" | "NUMBER" | "STRING" | "OP" | "EOF"
+    text: str  # original spelling
+    upper: str  # case-folded form (identifiers/keywords only; same as text otherwise)
+    col: int  # 0-based offset into the logical line's joined text
+    line: int = 0  # physical source line (assigned by the caller)
+    value: object = None  # NUMBER: int|float; STRING: decoded contents (quotes/escapes resolved)
+
+
+class LexError(ValueError):
+    def __init__(self, message: str, col: int):
+        super().__init__(message)
+        self.message = message
+        self.col = col
+
+
+def _number_value(text: str) -> int | float:
+    if text[0] == "&":
+        base = 16 if text[1] in "Hh" else 2
+        return int(text[2:], base)
+    if "." in text or "e" in text or "E" in text:
+        return float(text)
+    return int(text)
+
+
+def tokenize(text: str, line: int = 0) -> list[Token]:
+    """Tokenize one already-joined logical line. Raises `LexError` on an unrecognised character."""
+    tokens: list[Token] = []
+    i = 0
+    n = len(text)
+    while i < n:
+        ch = text[i]
+        if ch in " \t":
+            i += 1
+            continue
+        if ch == '"':
+            start = i
+            i += 1
+            out = []
+            while True:
+                if i >= n:
+                    raise LexError("unterminated string", start)
+                if text[i] == '"':
+                    if i + 1 < n and text[i + 1] == '"':
+                        out.append('"')
+                        i += 2
+                        continue
+                    i += 1
+                    break
+                out.append(text[i])
+                i += 1
+            raw = text[start:i]
+            tokens.append(Token("STRING", raw, raw, start, line, "".join(out)))
+            continue
+        m = _HEX_RE.match(text, i) or _BIN_RE.match(text, i)
+        if m:
+            raw = m.group(0)
+            tokens.append(Token("NUMBER", raw, raw.upper(), i, line, _number_value(raw)))
+            i = m.end()
+            continue
+        if (
+            ch == "."
+            and i + 1 < n
+            and text[i + 1].isdigit()
+            and tokens
+            and tokens[-1].kind == "IDENT"
+            and text[i - 1].isalnum()
+            or (
+                ch == "."
+                and i + 1 < n
+                and text[i + 1].isdigit()
+                and tokens
+                and tokens[-1].kind == "IDENT"
+                and text[i - 1] == "_"
+            )
+        ):
+            tokens.append(Token("OP", ".", ".", i, line))  # `Tmp.001`: a member name, not a number
+            m = re.compile(r"\w+").match(text, i + 1)
+            assert m is not None  # (a digit follows the `.`)
+            tokens.append(Token("IDENT", m.group(0), m.group(0).upper(), i + 1, line))
+            i = m.end()
+            continue
+        if ch.isdigit() or (ch == "." and i + 1 < n and text[i + 1].isdigit()):
+            m = _NUMBER_RE.match(text, i)
+            assert m is not None  # (a digit, or `.` and a digit)
+            raw = m.group(0)
+            value = _number_value(raw)
+            end = m.end()
+            if text[end : end + 1] in ("R", "r") and not (
+                text[end + 1 : end + 2].isalnum() or text[end + 1 : end + 2] == "_"
+            ):
+                end += 1  # `2.15R`: a double-precision literal (oracle, CR6/CR1000X, 2026-10-10)
+            tokens.append(Token("NUMBER", text[i:end], text[i:end], i, line, value))
+            i = end
+            continue
+        m = _IDENT_RE.match(text, i)
+        if m:
+            raw = m.group(0)
+            tokens.append(Token("IDENT", raw, raw.upper(), i, line))
+            i = m.end()
+            continue
+        m = _OP_RE.match(text, i)
+        if m:
+            raw = m.group(0)
+            tokens.append(Token("OP", raw, raw, i, line))
+            i = m.end()
+            continue
+        raise LexError(f"unrecognised character {ch!r}", i)
+    tokens.append(Token("EOF", "", "", n, line))
+    return tokens

opencrbasic/lsp/__init__.py

@@ -0,0 +1,5 @@
+"""Language server for CRBasic (LSP-01b). Protocol adapter only: no language rules live here.
+
+This package's `__init__` must stay free of third-party imports: analysis worker processes import
+`opencrbasic.lsp.worker` and must not load pygls. See `docs/lsp-api.md` "Language server".
+"""

opencrbasic/lsp/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m opencrbasic.lsp`: stdio language server. Imports stay inside the guard so spawned
+analysis workers (which re-import the main module) do not load pygls."""
+
+if __name__ == "__main__":
+    from .server import main
+
+    main()

opencrbasic/lsp/config.py

@@ -0,0 +1,202 @@
+"""Server configuration (`opencrbasic` section / initializationOptions) and entry discovery."""
+
+import codecs
+import os
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .. import profiles
+
+
+@dataclass(frozen=True)
+class Config:
+    entries: tuple[str, ...] = ("**/*.CR6",)
+    exclude: tuple[str, ...] = ()
+    logger: str = "cr6"
+    encoding: str = "utf-8"
+    debounce_ms: int = 300
+    analysis_timeout_ms: int = 10000
+    help_directory: str = ""  # "" : no help text
+    feature_wait_ms: int = 1500  # bounded wait for a fresh analysis (docs/lsp-api.md)
+    max_file_bytes: int = 2 * 1024 * 1024  # larger files are not analysed (docs/lsp-api.md "Bounds")
+    max_queued_jobs: int = 64  # entries with an analysis task at once; the rest wait
+    max_cache_mb: int = 256  # parsed programs kept for the language features
+    inlay_parameter_names: bool = True  # `inlayHints.parameterNames`
+    checks: tuple[tuple[str, str], ...] = ()  # `checks`: severity per check code (LSP layer)
+    coverage_notices: bool = False  # `coverageNotices`: publish coverage notices as hints
+
+    def analysis_key(self) -> tuple[str, str, int, tuple[tuple[str, str], ...], bool]:
+        """What changes every entry's analysis input or outcome."""
+        return (self.logger, self.encoding, self.max_file_bytes, self.checks, self.coverage_notices)
+
+    def entry_suffixes(self) -> frozenset[str]:
+        """Extensions (lower case) that make an opened file an entry program."""
+        return frozenset({".cr6"} | {ext for ext, name in profiles.EXTENSIONS.items() if name == self.logger})
+
+
+def _str_list(value: Any) -> tuple[str, ...] | None:
+    if isinstance(value, (list, tuple)) and all(isinstance(v, str) for v in value):
+        return tuple(value)
+    return None
+
+
+def _int(value: Any, minimum: int) -> int | None:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    value = int(value)
+    return value if value >= minimum else None
+
+
+def parse_config(options: Any, base: Config | None = None) -> tuple[Config, list[str]]:
+    """`base` overlaid with the recognised, valid keys of `options`. Returns the config and one
+    warning per rejected value (the base value is kept)."""
+    cfg = base or Config()
+    warnings: list[str] = []
+    if not isinstance(options, Mapping):
+        return cfg, warnings
+    changes: dict[str, Any] = {}
+    for key, attr in (("entries", "entries"), ("exclude", "exclude")):
+        if key in options:
+            value = _str_list(options[key])
+            if value is None:
+                warnings.append(f"ignoring {key!r}: expected a list of strings")
+            else:
+                changes[attr] = value
+    if "logger" in options:
+        value = options["logger"]
+        if isinstance(value, str) and value in profiles.PROFILES:
+            changes["logger"] = value
+        else:
+            warnings.append(f"ignoring 'logger': expected one of {', '.join(profiles.PROFILES)}")
+    if "encoding" in options:
+        value = options["encoding"]
+        try:
+            if not isinstance(value, str):
+                raise LookupError(value)
+            codecs.lookup(value)
+            changes["encoding"] = value
+        except LookupError:
+            warnings.append(f"ignoring 'encoding': unknown encoding {value!r}")
+    for key, attr, minimum in (
+        ("debounceMs", "debounce_ms", 0),
+        ("analysisTimeoutMs", "analysis_timeout_ms", 1),
+        ("featureWaitMs", "feature_wait_ms", 0),
+        ("maxFileBytes", "max_file_bytes", 1),
+        ("maxQueuedJobs", "max_queued_jobs", 1),
+        ("maxCacheMb", "max_cache_mb", 1),
+    ):
+        if key in options:
+            value = _int(options[key], minimum)
+            if value is None:
+                warnings.append(f"ignoring {key!r}: expected an integer >= {minimum}")
+            else:
+                changes[attr] = value
+    nested = options.get("inlayHints")
+    flat = "inlayHints.parameterNames"
+    if isinstance(nested, Mapping) and "parameterNames" in nested:
+        present, value = True, nested["parameterNames"]
+    else:
+        present, value = flat in options, options.get(flat)
+    if present:
+        if isinstance(value, bool):
+            changes["inlay_parameter_names"] = value
+        else:
+            warnings.append("ignoring 'inlayHints.parameterNames': expected a boolean")
+    if "checks" in options:
+        from .. import checkconfig, checks
+
+        try:
+            changes["checks"] = tuple(
+                sorted(checkconfig._severities(options["checks"], checks.DEFAULT_SEVERITY, "'checks'").items())
+            )
+        except checkconfig.ConfigError as e:
+            warnings.append(f"ignoring {e}")
+    if "coverageNotices" in options:
+        if isinstance(options["coverageNotices"], bool):
+            changes["coverage_notices"] = options["coverageNotices"]
+        else:
+            warnings.append("ignoring 'coverageNotices': expected a boolean")
+    if "helpDirectory" in options:
+        value = options["helpDirectory"]
+        if value is None or isinstance(value, str):
+            changes["help_directory"] = (value or "").strip()
+        else:
+            warnings.append("ignoring 'helpDirectory': expected a string")
+    return (Config(**{**cfg.__dict__, **changes}) if changes else cfg), warnings
+
+
+def glob_regex(pattern: str) -> re.Pattern[str]:
+    """Case-insensitive regex for a workspace-relative glob: `*`, `?`, `**`, `**/`, `{a,b}`."""
+    pat = pattern.replace("\\", "/")
+    while pat.startswith("./"):
+        pat = pat[2:]
+    out: list[str] = []
+    i = 0
+    depth = 0
+    while i < len(pat):
+        c = pat[i]
+        if pat.startswith("**/", i):
+            out.append("(?:.*/)?")
+            i += 3
+            continue
+        if pat.startswith("**", i):
+            out.append(".*")
+            i += 2
+            continue
+        if c == "*":
+            out.append("[^/]*")
+        elif c == "?":
+            out.append("[^/]")
+        elif c == "{":
+            out.append("(?:")
+            depth += 1
+        elif c == "}" and depth:
+            out.append(")")
+            depth -= 1
+        elif c == "," and depth:
+            out.append("|")
+        else:
+            out.append(re.escape(c))
+        i += 1
+    out.append(")" * depth)
+    return re.compile("".join(out), re.IGNORECASE | re.DOTALL)
+
+
+_SKIP_DIRS = {"node_modules", "__pycache__"}
+
+
+def discover(folders: list[Path], entries: tuple[str, ...], exclude: tuple[str, ...]) -> list[Path]:
+    """Files under `folders` matching an `entries` glob and no `exclude` glob (workspace-relative,
+    case-insensitive). Directories starting with `.` and `node_modules` are not walked."""
+    include = [glob_regex(p) for p in entries]
+    skip = [glob_regex(p) for p in exclude]
+    found: dict[Path, None] = {}
+    for folder in folders:
+        folder = Path(folder).absolute()
+        for root, dirs, files in os.walk(folder):
+            rel_root = Path(root).relative_to(folder).as_posix()
+            prefix = "" if rel_root == "." else rel_root + "/"
+            dirs[:] = sorted(
+                d
+                for d in dirs
+                if not d.startswith(".")
+                and d not in _SKIP_DIRS
+                and not any(rx.fullmatch(f"{prefix}{d}/_") for rx in skip)
+            )
+            for name in sorted(files):
+                rel = prefix + name
+                if any(rx.fullmatch(rel) for rx in include) and not any(rx.fullmatch(rel) for rx in skip):
+                    found[Path(root, name).absolute()] = None
+    return sorted(found)
+
+
+def watch_pattern() -> str:
+    """The `workspace/didChangeWatchedFiles` glob: library files and the program extensions of
+    every logger profile, each in lower and upper case (LSP globs are case-sensitive; the server
+    filters by the configured logger). A mixed-case extension such as `.Cr6` is not watched."""
+    suffixes = {".crb", ".cr6", *profiles.EXTENSIONS}
+    names = sorted({v for s in suffixes for v in (s.lower()[1:], s.upper()[1:])})
+    return "**/*.{" + ",".join(names) + "}"