execsql2 2.28.0__py3-none-any.whl → 2.30.0__py3-none-any.whl

execsql/lsp/document.py

@@ -17,26 +17,29 @@ from pathlib import Path
 from pygls.uris import from_fs_path
 
 from execsql.cli.lint import variables_defined_by
+from execsql.lsp._util import RX_METACOMMAND
 from execsql.script.ast import IncludeDirective, MetaCommandStatement, ScriptBlock
 from execsql.script.parser import parse_string
 
 __all__ = [
+    "FileFacts",
     "Location",
     "Reference",
     "ScriptIndex",
+    "file_facts",
     "file_uri",
     "index_script",
     "read_included",
     "same_file_key",
     "uri_for",
     "variable_at",
+    "is_file",
 ]
 
 # A substitution variable as written: !!name!!, !'!name!'!, !"!name!"! or the deferred !{name}!.
 # The lookahead also finds one written inside another's name: in !!N_!!GROUP!!_CHECKS!!,
 # execsql substitutes !!GROUP!! first, so GROUP is a use (N_ and _CHECKS are found too).
 _RX_VARIABLE = re.compile(r"""(?=!(['"]?)!(?P<name>[$&@~#+]?\w+)!\1!)|!\{(?P<deferred>[$&@~#+]?\w+)\}!""")
-_RX_METACOMMAND = re.compile(r"^\s*--\s*!x!\s*", re.I)
 
 
 @dataclass(frozen=True)
@@ -100,7 +103,7 @@ def read_included(path: Path) -> str | None:
         if not path.is_file() or path.stat().st_size > MAX_INCLUDED_BYTES:
             return None
         return path.read_text(encoding="utf-8")
-    except (OSError, UnicodeDecodeError):
+    except (OSError, ValueError, UnicodeDecodeError):  # ValueError: a NUL in the name
         return None
 
 
@@ -112,71 +115,150 @@ def _span_of(word: str, line: str, start: int = 0) -> tuple[int, int]:
     return start + m.start(), start + m.end()
 
 
+@dataclass(frozen=True)
+class _Define:
+    name: str  # as the script spells it
+    location: Location
+
+
+@dataclass(frozen=True)
+class _ScriptDef:
+    name: str  # lower case
+    location: Location
+    params: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class _ScriptCall:
+    location: Location
+    name: str  # lower case
+
+
+@dataclass(frozen=True)
+class _Include:
+    location: Location
+    target: str  # as written, quotes removed
+    resolved: str  # relative to the including file
+
+
+@dataclass(frozen=True)
+class FileFacts:
+    """What one file adds to an index, in the order indexing meets it.
+
+    It depends on the file's text and path alone, not on the files it
+    includes, so a caller may keep it while the text is unchanged, unless
+    :attr:`reads_ini`: a ``SUB_INI`` reads an INI file that can change on its own.
+    """
+
+    steps: tuple[_Define | _ScriptDef | _ScriptCall | _Include, ...]
+    references: tuple[Reference, ...]
+    reads_ini: bool = False
+
+    @property
+    def includes(self) -> tuple[str, ...]:
+        """The path of each file an ``INCLUDE`` in this file names, relative to it."""
+        return tuple(step.resolved for step in self.steps if isinstance(step, _Include))
+
+
+_RX_SUB_INI = re.compile(r"\s*SUB_INI\b", re.I)
+
+
+def file_facts(source: str, path: str | None, base_dir: str | None = None) -> FileFacts:
+    """The definitions, script blocks, ``INCLUDE`` targets and variable uses written in *source*.
+
+    Relative paths in it resolve against *path*'s directory, or for an
+    unsaved buffer (no *path*) against *base_dir*, else the working directory.
+    """
+    steps: list[_Define | _ScriptDef | _ScriptCall | _Include] = []
+    reads_ini = False
+    lines = source.splitlines()
+    script_dir = Path(path).parent if path else (Path(base_dir) if base_dir else None)
+    tree = parse_string(source, path or "<untitled>", errors=[])
+
+    for node in tree.walk():
+        row = node.span.start_line - 1
+        text = lines[row] if 0 <= row < len(lines) else ""
+        if isinstance(node, MetaCommandStatement):
+            reads_ini = reads_ini or _RX_SUB_INI.match(node.command) is not None
+            prefix = RX_METACOMMAND.match(text)
+            after = prefix.end("lead") if prefix else 0
+            for name in sorted(variables_defined_by(node.command, script_dir)):
+                start, end = _span_of(name, text, after)
+                found = text[start:end] if text[start:end].upper() == name else name  # keep the script's spelling
+                steps.append(_Define(found, Location(path, row, start, end)))
+        elif isinstance(node, ScriptBlock):
+            start, end = _span_of(node.name, text)
+            params = tuple(p.name for p in node.param_defs or [])
+            steps.append(_ScriptDef(node.name.lower(), Location(path, row, start, end), params))
+        elif isinstance(node, IncludeDirective) and node.is_execute_script:
+            start, end = _span_of(node.target, text)
+            steps.append(_ScriptCall(Location(path, row, start, end), node.target.lower()))
+        elif isinstance(node, IncludeDirective):
+            target = node.target.strip().strip("\"'")
+            start, end = _span_of(target, text) if target else (0, len(text))
+            resolved = Path(target) if Path(target).is_absolute() or script_dir is None else script_dir / target
+            steps.append(_Include(Location(path, row, start, end), target, str(resolved)))
+
+    references: list[Reference] = []
+    for row, text in enumerate(lines):
+        for m in _RX_VARIABLE.finditer(text):
+            group = "deferred" if m.group("deferred") else "name"
+            references.append(Reference(m.group(group), Location(path, row, m.start(group), m.end(group))))
+    return FileFacts(tuple(steps), tuple(references), reads_ini)
+
+
 def index_script(
     source: str,
     path: str | None,
     read: Callable[[Path], str | None] = read_included,
+    facts: Callable[[str, str | None, str | None], FileFacts] = file_facts,
+    base_dir: str | None = None,
 ) -> ScriptIndex:
     """Index *source*, the text of the file at *path* (``None`` for an unsaved buffer).
 
     *read* supplies an ``INCLUDE``d file's text; the server passes one that
-    prefers the editor's unsaved copy of a file that is open.
+    prefers the editor's unsaved copy of a file that is open.  *facts*
+    reads one file's text; the server passes one that remembers the answer.
+    An unsaved buffer's relative ``INCLUDE`` resolves against *base_dir*.
     """
     index = ScriptIndex(path=path)
-    _index_into(index, source, path, set(), read, top=True, budget=[MAX_INCLUDED_TOTAL_BYTES])
+    found = facts(source, path, None if path else base_dir)
+    _index_into(index, found, path, set(), read, facts, top=True, budget=[MAX_INCLUDED_TOTAL_BYTES])
     return index
 
 
 def _index_into(
     index: ScriptIndex,
-    source: str,
+    found: FileFacts,
     path: str | None,
     seen: set[str],
     read: Callable[[Path], str | None],
+    facts: Callable[[str, str | None, str | None], FileFacts],
     *,
     top: bool,
     budget: list[int],
 ) -> None:
     if path is not None:
-        seen.add(str(Path(path).resolve()))
-    lines = source.splitlines()
-    script_dir = Path(path).parent if path else None
-    tree = parse_string(source, path or "<untitled>", errors=[])
-
-    for node in tree.walk():
-        row = node.span.start_line - 1
-        text = lines[row] if 0 <= row < len(lines) else ""
-        if isinstance(node, MetaCommandStatement):
-            prefix = _RX_METACOMMAND.match(text)
-            after = prefix.end() if prefix else 0
-            for name in sorted(variables_defined_by(node.command, script_dir)):
-                start, end = _span_of(name, text, after)
-                found = text[start:end] if text[start:end].upper() == name else name  # keep the script's spelling
-                index.define(found, Location(path, row, start, end))
-        elif isinstance(node, ScriptBlock):
-            start, end = _span_of(node.name, text)
-            index.scripts.setdefault(node.name.lower(), Location(path, row, start, end))
-            index.script_params[node.name.lower()] = [p.name for p in node.param_defs or []]
-        elif isinstance(node, IncludeDirective) and node.is_execute_script:
+        seen.add(_resolved(path))
+    for step in found.steps:
+        if isinstance(step, _Define):
+            index.define(step.name, step.location)
+        elif isinstance(step, _ScriptDef):
+            index.scripts.setdefault(step.name, step.location)
+            index.script_params[step.name] = list(step.params)
+        elif isinstance(step, _ScriptCall):
             if top:
-                start, end = _span_of(node.target, text)
-                index.script_calls.append((Location(path, row, start, end), node.target.lower()))
-        elif isinstance(node, IncludeDirective):
-            target = node.target.strip().strip("\"'")
-            start, end = _span_of(target, text) if target else (0, len(text))
-            resolved = Path(target) if Path(target).is_absolute() or script_dir is None else script_dir / target
+                index.script_calls.append((step.location, step.name))
+        else:
             if top:
-                index.includes.append((Location(path, row, start, end), str(resolved)))
-            if "!" not in target and str(resolved.resolve()) not in seen and len(seen) < MAX_INCLUDED_FILES:
-                included = read(resolved)
+                index.includes.append((step.location, step.resolved))
+            if "!" not in step.target and _resolved(step.resolved) not in seen and len(seen) < MAX_INCLUDED_FILES:
+                included = read(Path(step.resolved))
                 if included is not None and len(included) <= budget[0]:
                     budget[0] -= len(included)
-                    _index_into(index, included, str(resolved), seen, read, top=False, budget=budget)
-
-    for row, text in enumerate(lines):
-        for m in _RX_VARIABLE.finditer(text):
-            group = "deferred" if m.group("deferred") else "name"
-            index.references.append(Reference(m.group(group), Location(path, row, m.start(group), m.end(group))))
+                    included_facts = facts(included, step.resolved, None)
+                    _index_into(index, included_facts, step.resolved, seen, read, facts, top=False, budget=budget)
+    index.references.extend(found.references)
 
 
 def uri_for(path: str | None, index: ScriptIndex, uri: str) -> str:
@@ -196,9 +278,25 @@ def file_uri(path: str, index: ScriptIndex) -> str | None:
     return index.open_uris.get(same_file_key(path)) or from_fs_path(path)
 
 
+def _resolved(path: str) -> str:
+    """*path* made absolute with links resolved, or just made absolute when the OS rejects it (too long, a NUL)."""
+    try:
+        return str(Path(path).resolve())
+    except (OSError, ValueError):
+        return os.path.abspath(path)
+
+
+def is_file(path: str | Path) -> bool:
+    """Whether *path* names a regular file; ``False`` for a name the OS rejects (too long, a NUL)."""
+    try:
+        return Path(path).is_file()
+    except (OSError, ValueError):
+        return False
+
+
 def same_file_key(path: str) -> str:
     """*path* resolved and case-folded where the file system ignores case, for comparing files."""
-    return os.path.normcase(str(Path(path).resolve()))
+    return os.path.normcase(_resolved(path))
 
 
 def variable_at(index: ScriptIndex, line: int, character: int) -> Reference | None:

execsql/lsp/hover.py

@@ -13,10 +13,10 @@ from lsprotocol import types
 
 from execsql.lsp.document import Reference, ScriptIndex, variable_at
 from execsql.metacommands import reference
+from execsql.lsp._util import RX_METACOMMAND, markdown, span
 
 __all__ = ["hover", "metacommand_for"]
 
-_RX_METACOMMAND = re.compile(r"^(?P<lead>\s*--\s*!x!\s*)(?P<command>.*?)\s*$", re.I)
 _RX_WORD = re.compile(r"[A-Za-z_]+")
 
 
@@ -44,14 +44,6 @@ def metacommand_for(command: str) -> reference.Metacommand | None:
     return best
 
 
-def _markdown(text: str) -> types.MarkupContent:
-    return types.MarkupContent(kind=types.MarkupKind.Markdown, value=text)
-
-
-def _range(line: int, start: int, end: int) -> types.Range:
-    return types.Range(start=types.Position(line=line, character=start), end=types.Position(line=line, character=end))
-
-
 def _syntax_block(forms: tuple[str, ...]) -> str:
     return "```\n" + "\n".join(forms) + "\n```"
 
@@ -94,9 +86,9 @@ def hover(index: ScriptIndex, source: str, line: int, character: int) -> types.H
     if ref is not None:
         content = _variable_hover(index, ref, lines)
         loc = ref.location
-        return types.Hover(contents=_markdown(content), range=_range(line, loc.start, loc.end)) if content else None
+        return types.Hover(contents=markdown(content), range=span(line, loc.start, loc.end)) if content else None
 
-    m = _RX_METACOMMAND.match(text)
+    m = RX_METACOMMAND.match(text)
     if not m or character < m.end("lead"):
         return None
 
@@ -106,7 +98,7 @@ def hover(index: ScriptIndex, source: str, line: int, character: int) -> types.H
             cond = reference.condition(word.group())
             if cond is not None and cond.name not in ("NOT", "OR"):
                 body = f"**{cond.name}** — conditional test\n\n{cond.summary}\n\n{_syntax_block(cond.forms)}\n\n[Reference]({cond.url})"
-                return types.Hover(contents=_markdown(body), range=_range(line, word.start(), word.end()))
+                return types.Hover(contents=markdown(body), range=span(line, word.start(), word.end()))
 
     entry = metacommand_for(m.group("command"))
     if entry is None:
@@ -116,4 +108,4 @@ def hover(index: ScriptIndex, source: str, line: int, character: int) -> types.H
     first_word = re.match(r"[A-Za-z_]+", text[start:])
     keyword_end = start + (written.end() if written else first_word.end() if first_word else 0)
     body = f"**{entry.keyword}** — {entry.category} metacommand\n\n{entry.summary}\n\n{_syntax_block(entry.forms)}\n\n[Reference]({entry.url})"
-    return types.Hover(contents=_markdown(body), range=_range(line, start, keyword_end))
+    return types.Hover(contents=markdown(body), range=span(line, start, keyword_end))

execsql/lsp/navigation.py

@@ -6,7 +6,7 @@ from pathlib import Path
 
 from lsprotocol import types
 
-from execsql.lsp.document import Location, ScriptIndex, file_uri, uri_for, variable_at
+from execsql.lsp.document import Location, ScriptIndex, file_uri, is_file, uri_for, variable_at
 from execsql.script.ast import (
     BatchBlock,
     IfBlock,
@@ -18,16 +18,13 @@ from execsql.script.ast import (
     SqlBlock,
 )
 from execsql.script.parser import parse_string
+from execsql.lsp._util import span
 
 __all__ = ["definition", "document_links", "document_symbols", "references"]
 
 
-def _range(line: int, start: int, end: int) -> types.Range:
-    return types.Range(start=types.Position(line=line, character=start), end=types.Position(line=line, character=end))
-
-
 def _lsp_location(loc: Location, index: ScriptIndex, uri: str) -> types.Location:
-    return types.Location(uri=uri_for(loc.path, index, uri), range=_range(loc.line, loc.start, loc.end))
+    return types.Location(uri=uri_for(loc.path, index, uri), range=span(loc.line, loc.start, loc.end))
 
 
 def _at(entries: list[tuple[Location, str]], line: int, character: int) -> str | None:
@@ -55,10 +52,10 @@ def definition(index: ScriptIndex, uri: str, line: int, character: int) -> list[
         return [_lsp_location(index.scripts[script], index, uri)]
 
     target = _at(index.includes, line, character)
-    if target is not None and Path(target).is_file():
+    if target is not None and is_file(target):
         uri_of_file = file_uri(target, index)
         if uri_of_file:
-            return [types.Location(uri=uri_of_file, range=_range(0, 0, 0))]
+            return [types.Location(uri=uri_of_file, range=span(0, 0, 0))]
     return []
 
 
@@ -84,10 +81,10 @@ def document_links(index: ScriptIndex) -> list[types.DocumentLink]:
     links = []
     for loc, target in index.includes:
         path = Path(target)
-        if path.is_file():
+        if is_file(path):
             uri = file_uri(target, index)
             if uri:
-                links.append(types.DocumentLink(range=_range(loc.line, loc.start, loc.end), target=uri))
+                links.append(types.DocumentLink(range=span(loc.line, loc.start, loc.end), target=uri))
     return links
 
 

execsql/lsp/server.py

@@ -6,6 +6,7 @@ import asyncio
 import logging
 import os
 from dataclasses import dataclass, field
+from collections.abc import Iterable
 from pathlib import Path
 from typing import Any
 
@@ -14,10 +15,11 @@ from pygls.lsp.server import LanguageServer
 from pygls.uris import to_fs_path
 
 from execsql import __version__
+from execsql.lsp.cache import IndexCache
 from execsql.lsp.code_actions import code_actions
 from execsql.lsp.completion import completions
-from execsql.lsp.diagnostics import diagnostics, too_deep_diagnostic
-from execsql.lsp.document import ScriptIndex, index_script, read_included, same_file_key
+from execsql.lsp.diagnostics import diagnostics, failure_diagnostic, too_deep_diagnostic
+from execsql.lsp.document import ScriptIndex, index_script, same_file_key
 from execsql.lsp.folding import folding_ranges
 from execsql.lsp.formatting import format_document
 from execsql.lsp.hover import hover
@@ -26,6 +28,8 @@ from execsql.lsp.navigation import definition, document_links, document_symbols,
 
 __all__ = ["ExecsqlLanguageServer", "create_server"]
 
+_log = logging.getLogger(__name__)
+
 # Pause after the last keystroke before linting, so a burst of typing lints once.
 LINT_DELAY_SECONDS = 0.2
 
@@ -54,34 +58,42 @@ class Settings:
     select: tuple[str, ...] = ()
     ignore: tuple[str, ...] = ()
     format_options: dict[str, Any] = field(default_factory=dict)  # format_document keywords, from [format]
+    config_files: tuple[str, ...] = ()  # the files read, lowest precedence first
 
 
 class ExecsqlLanguageServer(LanguageServer):
-    """Holds what the handlers share: each workspace folder's settings and pending lint tasks."""
+    """Holds what the handlers share: each workspace folder's settings, pending lint tasks and the index cache."""
 
     def __init__(self) -> None:
         super().__init__("execsql", __version__)
         self.settings: dict[str, Settings] = {}  # by same_file_key of each workspace folder
         self.fallback = Settings()  # for a file in no workspace folder
         self.pending: dict[str, asyncio.Task[Any]] = {}
+        self.cache = IndexCache()
 
     def load_settings(self) -> None:
         """Read ``[lint]`` and ``[format]`` for each workspace folder, as ``execsql lint`` / ``execsql format`` run there would.
 
-        execsql reads config files from the working directory, so each
-        folder's settings are read from inside it.  The server itself works
-        from the workspace root: a file in no folder gets the settings read
-        there, and an unsaved script's relative ``INCLUDE`` resolves there.
+        Each folder stands in for the working directory those commands read
+        config from; the server's own working directory never changes.  A file
+        in no folder gets the settings of :meth:`base_dir`.
         """
-        root = self.workspace.root_path
-        if root and os.path.isdir(root):
-            os.chdir(root)
-        self.fallback = self._read_settings(None)
+        self.fallback = self._read_settings(self.base_dir())
+        _log_settings("files in no workspace folder", self.fallback)
         self.settings = {}
         for folder in self.workspace.folders.values():
             path = to_fs_path(folder.uri)
             if path and os.path.isdir(path):
-                self.settings[same_file_key(path)] = self._read_settings(path)
+                self.settings[same_file_key(path)] = settings = self._read_settings(path)
+                _log_settings(path, settings)
+
+    def base_dir(self) -> str | None:
+        """The workspace root, if it still exists: an unsaved script's relative paths resolve there.
+
+        ``None`` (no root) leaves them to the server's working directory.
+        """
+        root = self.workspace.root_path
+        return root if root and os.path.isdir(root) else None
 
     def _read_settings(self, folder: str | None) -> Settings:
         """The settings ``execsql lint`` run from *folder* (the working directory if ``None``) reads.
@@ -91,11 +103,8 @@ class ExecsqlLanguageServer(LanguageServer):
         from execsql.cli.lint import resolve_selectors
         from execsql.cli.run import _tool_config
 
-        here = os.getcwd()
         try:
-            if folder is not None:
-                os.chdir(folder)
-            conf = _tool_config(None)
+            conf = _tool_config(None, start_dir=folder)
             return Settings(
                 select=resolve_selectors([conf.lint_select]) if conf.lint_select else (),
                 ignore=resolve_selectors([conf.lint_ignore]) if conf.lint_ignore else (),
@@ -105,14 +114,14 @@ class ExecsqlLanguageServer(LanguageServer):
                     "leading_comma": conf.format_leading_comma,
                     "rewrite_sql": conf.format_rewrite_sql,
                 },
+                config_files=tuple(conf.files_read),
             )
         except Exception as exc:  # a bad config must not take the server down
+            _log.warning("execsql config for %s: %s", folder or "the working directory", exc)
             self.window_show_message(
                 types.ShowMessageParams(type=types.MessageType.Warning, message=f"execsql config: {exc}"),
             )
             return Settings()
-        finally:
-            os.chdir(here)
 
     def settings_for(self, uri: str) -> Settings:
         """The settings of the innermost workspace folder holding *uri*'s file, else :attr:`fallback`."""
@@ -124,7 +133,7 @@ class ExecsqlLanguageServer(LanguageServer):
         return self.settings[max(holding, key=len)] if holding else self.fallback
 
     def index(self, uri: str) -> ScriptIndex:
-        """The current document's index (rebuilt per request: a few milliseconds).
+        """The current document's index, rebuilt per request from :attr:`cache`d per-file facts.
 
         A script the parser cannot handle (nesting past Python's recursion
         limit) gets an empty index, so features fall back to what needs none.
@@ -132,9 +141,12 @@ class ExecsqlLanguageServer(LanguageServer):
         document = self.workspace.get_text_document(uri)
         path = to_fs_path(uri)
         try:
-            index = index_script(document.source, path, self.read_included)
+            index = index_script(document.source, path, self.read_included, self.cache.facts, self.base_dir())
         except RecursionError:
             index = ScriptIndex(path=path)
+        except Exception:  # the features that need an index answer with nothing; the cause goes to the log
+            _log.exception("execsql lsp: could not index %s", uri)
+            index = ScriptIndex(path=path)
         index.open_uris = self.open_uris()
         return index
 
@@ -161,7 +173,7 @@ class ExecsqlLanguageServer(LanguageServer):
         uri = self.open_uris().get(same_file_key(str(path)))
         if uri is not None:
             return self.workspace.get_text_document(uri).source
-        return read_included(path)
+        return self.cache.text(path)
 
     def supports_snippets(self) -> bool:
         caps = self.client_capabilities.text_document
@@ -173,17 +185,41 @@ class ExecsqlLanguageServer(LanguageServer):
         document = self.workspace.get_text_document(uri)
         settings = self.settings_for(uri)
         try:
-            found = diagnostics(document.source, to_fs_path(uri), settings.select, settings.ignore)
+            found = diagnostics(document.source, to_fs_path(uri), settings.select, settings.ignore, self.base_dir())
         except RecursionError:
             found = [too_deep_diagnostic()]
+        except Exception as exc:  # shown in the editor, not lost in an unawaited task
+            _log.exception("execsql lsp: could not lint %s", uri)
+            found = [failure_diagnostic(exc)]
         self.text_document_publish_diagnostics(
             types.PublishDiagnosticsParams(uri=uri, version=document.version, diagnostics=found),
         )
 
-    def publish_all(self) -> None:
-        """Lint every open document again: a file one of them includes, or the config, changed."""
+    def relint(self, changed: Iterable[str] | None = None) -> None:
+        """Lint again, after :data:`LINT_DELAY_SECONDS`, each open document a change to the *changed* files can affect.
+
+        Lint reads no included file's text; it checks only that each file a
+        script ``INCLUDE``s exists.  So a document is affected by a change to
+        itself or to a file it includes.  ``None`` means everything changed
+        (the config, the workspace folders).  Going through the debounce, the
+        editor's save and its file watcher's report of the same save lint once.
+        """
+        keys = None if changed is None else {same_file_key(path) for path in changed}
         for uri in list(self.workspace.text_documents):
-            self.publish(uri)
+            if keys is None or self._affected(uri, keys):
+                self.publish_later(uri)
+
+    def _affected(self, uri: str, keys: set[str]) -> bool:
+        path = to_fs_path(uri)
+        if path is None:
+            return False
+        if same_file_key(path) in keys:
+            return True
+        try:
+            facts = self.cache.facts(self.workspace.get_text_document(uri).source, path)
+        except Exception:  # when unsure, lint again
+            return True
+        return any(same_file_key(target) in keys for target in facts.includes)
 
     def watch_files(self) -> None:
         """Ask the client to report changes to :data:`WATCHED_FILES`, if it can."""
@@ -219,6 +255,36 @@ class ExecsqlLanguageServer(LanguageServer):
         self.pending[uri] = asyncio.ensure_future(run())
 
 
+def _log_settings(where: str, settings: Settings) -> None:
+    _log.info(
+        "settings for %s: config files %s; lint select %s, ignore %s; format %s",
+        where,
+        ", ".join(settings.config_files) or "none",
+        ",".join(settings.select) or "all",
+        ",".join(settings.ignore) or "none",
+        settings.format_options or "defaults",
+    )
+
+
+def startup_record() -> str:
+    """What a bug report needs first: which execsql, run by which Python, with which optional parts."""
+    import sys
+    from importlib.metadata import PackageNotFoundError, version
+    from importlib.util import find_spec
+
+    def installed(name: str) -> str:
+        try:
+            return version(name)
+        except PackageNotFoundError:
+            return "not installed"
+
+    formatter = "available" if find_spec("sqlglot") is not None else "not installed (Format Document needs it)"
+    return (
+        f"execsql lsp {__version__}; Python {sys.version.split()[0]} at {sys.executable}; "
+        f"pygls {installed('pygls')}; formatter {formatter}"
+    )
+
+
 def create_server() -> ExecsqlLanguageServer:
     """A server with every feature registered."""
     server = ExecsqlLanguageServer()
@@ -228,9 +294,19 @@ def create_server() -> ExecsqlLanguageServer:
 
     @server.feature(types.INITIALIZED)
     def initialized(ls: ExecsqlLanguageServer, params: types.InitializedParams) -> None:
+        _log.info(startup_record())
+        folders = [to_fs_path(f.uri) or f.uri for f in ls.workspace.folders.values()]
+        _log.info("workspace folders: %s", ", ".join(folders) or "none")
         ls.load_settings()
         ls.watch_files()
 
+    @server.feature(types.SHUTDOWN)
+    def shutdown(ls: ExecsqlLanguageServer, params: None) -> None:
+        # No diagnostics may follow the answer to shutdown.
+        for task in ls.pending.values():
+            task.cancel()
+        ls.pending.clear()
+
     @server.feature(types.TEXT_DOCUMENT_DID_OPEN)
     def did_open(ls: ExecsqlLanguageServer, params: types.DidOpenTextDocumentParams) -> None:
         ls.publish(params.text_document.uri)
@@ -242,19 +318,25 @@ def create_server() -> ExecsqlLanguageServer:
     @server.feature(types.TEXT_DOCUMENT_DID_SAVE)
     def did_save(ls: ExecsqlLanguageServer, params: types.DidSaveTextDocumentParams) -> None:
         # Another open script may INCLUDE this one; a client that cannot watch files reports nothing else.
-        ls.publish_all()
+        path = to_fs_path(params.text_document.uri)
+        ls.relint([path] if path else [])
 
     @server.feature(types.WORKSPACE_DID_CHANGE_WATCHED_FILES)
     def did_change_watched_files(ls: ExecsqlLanguageServer, params: types.DidChangeWatchedFilesParams) -> None:
-        if any(Path(to_fs_path(change.uri) or "").name.lower() == "execsql.conf" for change in params.changes):
+        paths = [path for change in params.changes if (path := to_fs_path(change.uri))]
+        for path in paths:
+            ls.cache.forget(path)
+        if any(Path(path).name.lower() == "execsql.conf" for path in paths):
             ls.load_settings()
-        ls.publish_all()
+            ls.relint()
+        else:
+            ls.relint(paths)
 
     @server.feature(types.WORKSPACE_DID_CHANGE_WORKSPACE_FOLDERS)
     def did_change_folders(ls: ExecsqlLanguageServer, params: types.DidChangeWorkspaceFoldersParams) -> None:
         # pygls has already updated ls.workspace.folders.
         ls.load_settings()
-        ls.publish_all()
+        ls.relint()
 
     @server.feature(types.TEXT_DOCUMENT_DID_CLOSE)
     def did_close(ls: ExecsqlLanguageServer, params: types.DidCloseTextDocumentParams) -> None: