execsql2 2.26.0__tar.gz → 2.27.0__tar.gz

{execsql2-2.26.0 → execsql2-2.27.0}/.github/dependabot.yml

@@ -51,3 +51,12 @@ updates:
           pre-commit-hooks:
               patterns:
                   - "*"
+    # The VS Code extension's language client and its packaging tool.
+    - package-ecosystem: npm
+      directory: /extras/vscode-execsql
+      schedule:
+          interval: weekly
+      groups:
+          vscode-extension:
+              patterns:
+                  - "*"

{execsql2-2.26.0 → execsql2-2.27.0}/.github/workflows/ci-cd.yml

@@ -110,6 +110,37 @@ jobs:
               env:
                   SKIP: mypy
 
+    vscode-extension:
+        name: vscode-extension
+        runs-on: ubuntu-latest
+        permissions:
+            contents: read
+        steps:
+            - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+            - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
+              with:
+                  node-version: "22"
+            # Dependencies come from the committed package-lock.json, and no
+            # install script of any dependency runs.
+            - name: Install dependencies
+              working-directory: extras/vscode-execsql
+              run: npm ci --ignore-scripts --no-audit --no-fund
+            # A release's extension carries the release's version (VS Code
+            # versions are X.Y.Z, so a pre-release suffix is dropped).
+            - name: Set the extension version from the tag
+              if: startsWith(github.ref, 'refs/tags/v')
+              working-directory: extras/vscode-execsql
+              run: |
+                  version="$(echo "${GITHUB_REF_NAME#v}" | grep -oE '^[0-9]+\.[0-9]+\.[0-9]+')"
+                  npm pkg set version="$version"
+            - name: Package the .vsix
+              working-directory: extras/vscode-execsql
+              run: ./node_modules/.bin/vsce package --out "../../execsql-syntax.vsix"
+            - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+              with:
+                  name: vscode-extension
+                  path: execsql-syntax.vsix
+
     docs:
         name: docs
         runs-on: ubuntu-latest
@@ -338,7 +369,7 @@ jobs:
     build:
         name: Build distribution 📦
         runs-on: ubuntu-latest
-        needs: [ lint, typecheck, pre-commit, formatter-corpus, typer-floor, docs, tests, integration-tests ]
+        needs: [ lint, typecheck, pre-commit, formatter-corpus, typer-floor, docs, tests, integration-tests, vscode-extension ]
         # Deliberately NOT gated on tags: packaging breaks must surface on a PR,
         # not at release time. Only publish/generate-release below are tag-gated.
         permissions:
@@ -403,7 +434,7 @@ jobs:
         name: Generate GitHub Release
         # After the PyPI upload, so a release is never announced for a
         # version that pip cannot install.
-        needs: [ publish ]
+        needs: [ publish, vscode-extension ]
         if: startsWith(github.ref, 'refs/tags/v')
         runs-on: ubuntu-latest
         permissions:
@@ -416,6 +447,11 @@ jobs:
               with:
                   name: ${{ github.event.repository.name }}
                   path: dist/
+            - name: Download the VS Code extension
+              uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
+              with:
+                  name: vscode-extension
+                  path: dist/
             - name: Detect pre-release tag
               id: tag
               # PEP 440 pre-release suffix (a1, b2, rc1) on the tag -> mark the

{execsql2-2.26.0 → execsql2-2.27.0}/.gitignore

@@ -56,3 +56,7 @@ PROMPTS.md
 audit/
 AGENTS.md
 .codex/
+
+# VS Code extension dependencies (npm ci in extras/vscode-execsql)
+node_modules/
+*.vsix

{execsql2-2.26.0 → execsql2-2.27.0}/.pre-commit-config.yaml

@@ -13,12 +13,12 @@ repos:
       - id: check-hooks-apply
   # Protect secrets using Gitleaks
   - repo: https://github.com/zricethezav/gitleaks
-    rev: v8.30.0
+    rev: v8.30.1
     hooks:
       - id: gitleaks
   # uv lockfile management
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.11.1
+    rev: 0.12.23
     hooks:
       - id: uv-lock
   # Base hooks
@@ -44,7 +44,7 @@ repos:
       - id: mdformat
         language: python
         additional_dependencies:
-          - mdformat-mkdocs==5.1.1
+          - mdformat-mkdocs==5.3.0
         exclude: |
           (?x)^(
             \.claude/.*|
@@ -56,7 +56,7 @@ repos:
           )$
   # Markdown lint
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.48.0
+    rev: v0.49.1
     hooks:
       - id: markdownlint
         types: [file]
@@ -64,13 +64,13 @@ repos:
         args: [--disable, MD013]
   # Spell check
   - repo: https://github.com/crate-ci/typos
-    rev: v1.44.0
+    rev: v1.51.0
     hooks:
       - id: typos
         args: [--force-exclude]
   # Lint & format with ruff
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.7
+    rev: v0.16.10
     hooks:
       - id: ruff-check
         args: [--config=pyproject.toml, --exit-non-zero-on-fix]

{execsql2-2.26.0 → execsql2-2.27.0}/.readthedocs.yaml

@@ -9,7 +9,7 @@ build:
     python: "3.13"
   jobs:
     install:
-      - pip install "zensical==0.0.28" mkdocstrings-python
+      - pip install "zensical==0.0.67" mkdocstrings-python
       - pip install -e .
     pre_build:
       - cp CHANGELOG.md docs/about/change_log.md

{execsql2-2.26.0 → execsql2-2.27.0}/CHANGELOG.md

@@ -13,6 +13,38 @@ ______________________________________________________________________
 
 ______________________________________________________________________
 
+## [2.27.0] - 2026-10-12
+
+### Added
+
+- **`execsql lsp`**, a language server for editors. Install the new `lsp` extra (`uv tool install "execsql2[lsp]"`; to add it to an existing install, name the extras you already have, e.g. `"execsql2[postgres,lsp]"`); setup for VS Code, Neovim, Helix and other editors is in the new Editor Support guide. It provides:
+
+    - `execsql lint` findings as you type, using the workspace's `[lint]` settings;
+    - completion of metacommands (as fill-in templates of their documented syntax), conditional tests, variables and export formats;
+    - hover explanations of metacommands, conditional tests and variables;
+    - Go to Definition, Find All References, Rename Symbol (variables), the outline and `INCLUDE` links;
+    - folding of `IF` branches, `LOOP`, `SCRIPT`, `BATCH` and `SQL` blocks, multi-line statements and comments;
+    - quick fixes for misspelled metacommands, conditional tests and variables (P003, P004, V001) and split dollar-quoted bodies (P002);
+    - Format Document, the same as `execsql format` with the workspace's `[format]` settings;
+    - `execsql.conf` read again when it changes, and open scripts linted again when a file they `INCLUDE` changes;
+    - each folder of a multi-root workspace linted and formatted with its own `execsql.conf`.
+
+    The server never runs a script or connects to a database. It reads the open scripts, the files they `INCLUDE` or name in `SUB_INI` (regular files of bounded size), and the configuration files `execsql lint` reads.
+
+- **VS Code extension** starts `execsql lsp` for `.sql` files, with `execsql.server.path` and `execsql.server.enabled` settings and an **execsql: Restart Language Server** command. Each GitHub release attaches it as `execsql-syntax.vsix`; install with `code --install-extension execsql-syntax.vsix`. The server starts only in a trusted folder; highlighting works in any. `execsql.server.path` is a command name looked up in PATH or an absolute path, and the extension never runs an `execsql` found in the open folder.
+
+### Changed
+
+- **`lsp` is a command name:** `execsql lsp` starts the language server. Run a script file named `lsp` (with no extension) as `execsql run lsp`.
+- **`execsql list metacommands`** lists every metacommand (all 95; some were missing) with its category and a one-line summary, and `execsql list metacommands <KEYWORD>` shows that metacommand's syntax, as the reference docs write it, with a link. In `--output-format json`, `syntax` is now the full first syntax line, and each entry adds `forms`, `category`, `summary` and `url`. Read `forms` for every syntax line.
+
+### Fixed
+
+- **DuckDB `TIMESTAMPTZ` values** are read instead of stopping the script: the `duckdb` and `all-db` extras now install `pytz`, which duckdb needs for them.
+- **`CONFIG MAX_INT <n>`** works as documented; it stopped with `Unknown metacommand`, and only the bare `MAX_INT <n>` (still accepted) was recognized.
+
+______________________________________________________________________
+
 ## [2.26.0] - 2026-10-09
 
 ### Added

{execsql2-2.26.0 → execsql2-2.27.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: execsql2
-Version: 2.26.0
+Version: 2.27.0
 Summary: Runs a SQL script against a PostgreSQL, SQLite, MariaDB/MySQL, DuckDB, Firebird, MS-Access, MS-SQL-Server, or Oracle database, or an ODBC DSN. Provides metacommands to import and export data, copy data between databases, conditionally execute SQL and metacommands, and dynamically alter SQL and metacommands with substitution variables.
 Project-URL: Homepage, https://execsql2.readthedocs.io
 Project-URL: Repository, https://github.com/geocoug/execsql
@@ -49,14 +49,17 @@ Requires-Dist: duckdb>=1.0; extra == 'all'
 Requires-Dist: firebird-driver>=1.10; extra == 'all'
 Requires-Dist: jinja2>=3.1; extra == 'all'
 Requires-Dist: keyring>=25.0; extra == 'all'
+Requires-Dist: lsprotocol>=2025.0.0; extra == 'all'
 Requires-Dist: odfpy>=1.4; extra == 'all'
 Requires-Dist: openpyxl>=3.1; extra == 'all'
 Requires-Dist: oracledb>=3.0; extra == 'all'
 Requires-Dist: pg-upsert>=1.25.0; extra == 'all'
 Requires-Dist: polars>=1.0; extra == 'all'
 Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'all'
+Requires-Dist: pygls<3,>=2.1; extra == 'all'
 Requires-Dist: pymysql>=1.1; extra == 'all'
 Requires-Dist: pyodbc>=5.0; extra == 'all'
+Requires-Dist: pytz; extra == 'all'
 Requires-Dist: pyyaml>=6.0; extra == 'all'
 Requires-Dist: sqlglot<30.22,>=30.21.0; extra == 'all'
 Requires-Dist: tables>=3.10; extra == 'all'
@@ -69,6 +72,7 @@ Requires-Dist: oracledb>=3.0; extra == 'all-db'
 Requires-Dist: psycopg[binary]<4,>=3.1; extra == 'all-db'
 Requires-Dist: pymysql>=1.1; extra == 'all-db'
 Requires-Dist: pyodbc>=5.0; extra == 'all-db'
+Requires-Dist: pytz; extra == 'all-db'
 Provides-Extra: auth
 Requires-Dist: keyring>=25.0; extra == 'auth'
 Provides-Extra: auth-encrypted
@@ -83,13 +87,16 @@ Requires-Dist: build>=1.2.2.post1; extra == 'dev'
 Requires-Dist: bump-my-version>=1.2.7; extra == 'dev'
 Requires-Dist: defusedxml>=0.7; extra == 'dev'
 Requires-Dist: jinja2>=3.1; extra == 'dev'
+Requires-Dist: lsprotocol>=2025.0.0; extra == 'dev'
 Requires-Dist: mkdocstrings-python>=2.0.3; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: odfpy>=1.4; extra == 'dev'
 Requires-Dist: openpyxl>=3.1; extra == 'dev'
 Requires-Dist: polars>=1.0; extra == 'dev'
 Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
+Requires-Dist: pygls<3,>=2.1; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest-lsp>=1.0; extra == 'dev'
 Requires-Dist: pyyaml>=6.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
 Requires-Dist: sqlglot<30.22,>=30.21.0; extra == 'dev'
@@ -97,9 +104,10 @@ Requires-Dist: tables>=3.10; extra == 'dev'
 Requires-Dist: tox-uv>=1.13.1; extra == 'dev'
 Requires-Dist: twine>=6.1.0; extra == 'dev'
 Requires-Dist: xlrd>=2.0; extra == 'dev'
-Requires-Dist: zensical==0.0.28; extra == 'dev'
+Requires-Dist: zensical==0.0.67; extra == 'dev'
 Provides-Extra: duckdb
 Requires-Dist: duckdb>=1.0; extra == 'duckdb'
+Requires-Dist: pytz; extra == 'duckdb'
 Provides-Extra: firebird
 Requires-Dist: firebird-driver>=1.10; extra == 'firebird'
 Provides-Extra: formats
@@ -113,6 +121,10 @@ Requires-Dist: tables>=3.10; extra == 'formats'
 Requires-Dist: xlrd>=2.0; extra == 'formats'
 Provides-Extra: formatter
 Requires-Dist: sqlglot<30.22,>=30.21.0; extra == 'formatter'
+Provides-Extra: lsp
+Requires-Dist: lsprotocol>=2025.0.0; extra == 'lsp'
+Requires-Dist: pygls<3,>=2.1; extra == 'lsp'
+Requires-Dist: sqlglot<30.22,>=30.21.0; extra == 'lsp'
 Provides-Extra: map
 Requires-Dist: tkintermapview>=1.29; extra == 'map'
 Provides-Extra: mssql
@@ -158,15 +170,16 @@ Description-Content-Type: text/markdown
 
 Scripts are ordinary SQL plus metacommands embedded in comments (`-- !x!`), which add importing and exporting data, copying between databases, conditional execution, looping, substitution variables, and interactive prompts. Because the metacommands live in comments, the scripts stay valid SQL and other tools (`psql`, `sqlcmd`, your editor) ignore them.
 
-| Command                                    | What it does                                                            | Needs a database? |
-| ------------------------------------------ | ----------------------------------------------------------------------- | ----------------- |
-| `execsql format`                           | Normalize keywords, indentation, and SQL layout                         | No                |
-| `execsql lint`                             | Static analysis: structure, unknown metacommands, variables, targets    | No                |
-| `execsql run`                              | Run the script against PostgreSQL, MySQL, SQLite, DuckDB, …             | Yes               |
-| `execsql config`                           | Show every config option, its value, and the file that set it           | No                |
-| `execsql list`                             | Metacommands, encodings, plugins, or the keyword vocabulary             | No                |
-| `execsql init`                             | Set up a project: config file, a script with a header, pre-commit hooks | No                |
-| [VS Code extension](extras/vscode-execsql) | Syntax highlighting for metacommands and variables                      | No                |
+| Command                                    | What it does                                                                                                                                                          | Needs a database? |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `execsql format`                           | Normalize keywords, indentation, and SQL layout                                                                                                                       | No                |
+| `execsql lint`                             | Static analysis: structure, unknown metacommands, variables, targets                                                                                                  | No                |
+| `execsql run`                              | Run the script against PostgreSQL, MySQL, SQLite, DuckDB, …                                                                                                           | Yes               |
+| `execsql config`                           | Show every config option, its value, and the file that set it                                                                                                         | No                |
+| `execsql list`                             | Metacommands, encodings, plugins, or the keyword vocabulary                                                                                                           | No                |
+| `execsql init`                             | Set up a project: config file, a script with a header, pre-commit hooks                                                                                               | No                |
+| `execsql lsp`                              | [Language server](https://execsql2.readthedocs.io/en/latest/guides/editors/): lint findings, completion, hover, navigation, quick fixes and formatting in your editor | No                |
+| [VS Code extension](extras/vscode-execsql) | Highlighting plus everything `execsql lsp` provides                                                                                                                   | No                |
 
 `format` and `lint` take files or directories.
 
@@ -451,7 +464,7 @@ execsql format --no-sql --in-place scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.26.0
+    rev: v2.27.0
     hooks:
       - id: execsql-format
       - id: execsql-lint
@@ -459,17 +472,18 @@ repos:
 
 The format hook rewrites `*.sql` files in place by default; the lint hook fails the commit when a script has a lint error. See the [formatter documentation](https://execsql2.readthedocs.io/en/latest/guides/formatter/) for `--check`, `--indent`, and other options.
 
-## VS Code Syntax Highlighting
+## VS Code
 
-A VS Code extension for execsql syntax highlighting is included in [`extras/vscode-execsql`](extras/vscode-execsql). It injects a TextMate grammar into `.sql` files, adding highlighting for `-- !x!` metacommand markers, keywords (control flow, block, action, directive), variable substitutions (`!!var!!`, `!{var}!`), built-in functions, export formats, and config options, all layered on top of standard SQL highlighting.
-
-To install, symlink the extension folder into your VS Code extensions directory:
+The VS Code extension in [`extras/vscode-execsql`](extras/vscode-execsql) highlights execsql syntax in `.sql` files (metacommand markers, keywords, variable substitutions, export formats, config options) on top of standard SQL highlighting, and starts the execsql language server for lint findings as you type and completion. Each GitHub release has the extension attached as `execsql-syntax.vsix`:
 
 ```sh
-ln -s /path/to/execsql/extras/vscode-execsql ~/.vscode/extensions/execsql-syntax
+uv tool install "execsql2[lsp]"                     # the language server
+code --install-extension execsql-syntax.vsix        # the extension, from the release
 ```
 
-See the [extension README](extras/vscode-execsql/README.md) for Windows instructions, color customization, and troubleshooting.
+If execsql is already installed with other extras, name them too, e.g. `uv tool install "execsql2[postgres,lsp]"` or `pipx install --force "execsql2[postgres,lsp]"`: the new list replaces the old one (see [Adding an extra later](https://execsql2.readthedocs.io/en/latest/getting-started/installation/#adding-an-extra-later)).
+
+Other editors use the language server directly: see [Editor Support](https://execsql2.readthedocs.io/en/latest/guides/editors/). The [extension README](extras/vscode-execsql/README.md) covers settings, installing from a clone, color customization, and troubleshooting.
 
 ## Templates
 

{execsql2-2.26.0 → execsql2-2.27.0}/README.md

@@ -27,15 +27,16 @@
 
 Scripts are ordinary SQL plus metacommands embedded in comments (`-- !x!`), which add importing and exporting data, copying between databases, conditional execution, looping, substitution variables, and interactive prompts. Because the metacommands live in comments, the scripts stay valid SQL and other tools (`psql`, `sqlcmd`, your editor) ignore them.
 
-| Command                                    | What it does                                                            | Needs a database? |
-| ------------------------------------------ | ----------------------------------------------------------------------- | ----------------- |
-| `execsql format`                           | Normalize keywords, indentation, and SQL layout                         | No                |
-| `execsql lint`                             | Static analysis: structure, unknown metacommands, variables, targets    | No                |
-| `execsql run`                              | Run the script against PostgreSQL, MySQL, SQLite, DuckDB, …             | Yes               |
-| `execsql config`                           | Show every config option, its value, and the file that set it           | No                |
-| `execsql list`                             | Metacommands, encodings, plugins, or the keyword vocabulary             | No                |
-| `execsql init`                             | Set up a project: config file, a script with a header, pre-commit hooks | No                |
-| [VS Code extension](extras/vscode-execsql) | Syntax highlighting for metacommands and variables                      | No                |
+| Command                                    | What it does                                                                                                                                                          | Needs a database? |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `execsql format`                           | Normalize keywords, indentation, and SQL layout                                                                                                                       | No                |
+| `execsql lint`                             | Static analysis: structure, unknown metacommands, variables, targets                                                                                                  | No                |
+| `execsql run`                              | Run the script against PostgreSQL, MySQL, SQLite, DuckDB, …                                                                                                           | Yes               |
+| `execsql config`                           | Show every config option, its value, and the file that set it                                                                                                         | No                |
+| `execsql list`                             | Metacommands, encodings, plugins, or the keyword vocabulary                                                                                                           | No                |
+| `execsql init`                             | Set up a project: config file, a script with a header, pre-commit hooks                                                                                               | No                |
+| `execsql lsp`                              | [Language server](https://execsql2.readthedocs.io/en/latest/guides/editors/): lint findings, completion, hover, navigation, quick fixes and formatting in your editor | No                |
+| [VS Code extension](extras/vscode-execsql) | Highlighting plus everything `execsql lsp` provides                                                                                                                   | No                |
 
 `format` and `lint` take files or directories.
 
@@ -320,7 +321,7 @@ execsql format --no-sql --in-place scripts/
 ```yaml
 repos:
   - repo: https://github.com/geocoug/execsql
-    rev: v2.26.0
+    rev: v2.27.0
     hooks:
       - id: execsql-format
       - id: execsql-lint
@@ -328,17 +329,18 @@ repos:
 
 The format hook rewrites `*.sql` files in place by default; the lint hook fails the commit when a script has a lint error. See the [formatter documentation](https://execsql2.readthedocs.io/en/latest/guides/formatter/) for `--check`, `--indent`, and other options.
 
-## VS Code Syntax Highlighting
+## VS Code
 
-A VS Code extension for execsql syntax highlighting is included in [`extras/vscode-execsql`](extras/vscode-execsql). It injects a TextMate grammar into `.sql` files, adding highlighting for `-- !x!` metacommand markers, keywords (control flow, block, action, directive), variable substitutions (`!!var!!`, `!{var}!`), built-in functions, export formats, and config options, all layered on top of standard SQL highlighting.
-
-To install, symlink the extension folder into your VS Code extensions directory:
+The VS Code extension in [`extras/vscode-execsql`](extras/vscode-execsql) highlights execsql syntax in `.sql` files (metacommand markers, keywords, variable substitutions, export formats, config options) on top of standard SQL highlighting, and starts the execsql language server for lint findings as you type and completion. Each GitHub release has the extension attached as `execsql-syntax.vsix`:
 
 ```sh
-ln -s /path/to/execsql/extras/vscode-execsql ~/.vscode/extensions/execsql-syntax
+uv tool install "execsql2[lsp]"                     # the language server
+code --install-extension execsql-syntax.vsix        # the extension, from the release
 ```
 
-See the [extension README](extras/vscode-execsql/README.md) for Windows instructions, color customization, and troubleshooting.
+If execsql is already installed with other extras, name them too, e.g. `uv tool install "execsql2[postgres,lsp]"` or `pipx install --force "execsql2[postgres,lsp]"`: the new list replaces the old one (see [Adding an extra later](https://execsql2.readthedocs.io/en/latest/getting-started/installation/#adding-an-extra-later)).
+
+Other editors use the language server directly: see [Editor Support](https://execsql2.readthedocs.io/en/latest/guides/editors/). The [extension README](extras/vscode-execsql/README.md) covers settings, installing from a clone, color customization, and troubleshooting.
 
 ## Templates
 

{execsql2-2.26.0 → execsql2-2.27.0}/docs/about/divergence.md

@@ -71,6 +71,7 @@ ______________________________________________________________________
 | Fix                             | Description                                                                                                                                                                                                                                                                                                              |
 | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Variable EXECUTE SCRIPT targets | `EXECUTE SCRIPT !!#var!!` now works — the parser accepts substitution variable patterns as script identifiers, and the executor resolves them at runtime.                                                                                                                                                                |
+| `CONFIG MAX_INT`                | The documented `CONFIG MAX_INT <n>` form is accepted. Upstream documented it but recognized only the bare `MAX_INT <n>`, which still works.                                                                                                                                                                              |
 | Quoted parameter defaults       | `BEGIN SCRIPT proc(name="value")` previously stored the literal `"value"` (with surrounding quotes), causing substitutions like `WRITE "!!#name!!"` to expand to `WRITE ""value""` and fail. Defaults now strip surrounding quotes at parse time, matching the `wo_quotes` handling already applied to passed arguments. |
 
 ### Conditional Tests
@@ -134,8 +135,9 @@ today — a script named exactly like a command — is recorded under
 | `execsql format` | The formatter, reached through the main command. It replaced the standalone `execsql-format` console script, which was removed. The published pre-commit hook **id** is still `execsql-format`, so downstream `.pre-commit-config.yaml` files need no change — only the hook's internal `entry` moved. Formatter for normalizing metacommand indentation and uppercasing SQL keywords. Supports `--check`, `--in-place`, `--indent N` (controls both metacommand and SQL indentation), `--leading-comma` (commas at start of lines), `--no-sql` (skip SQL reformatting), `--rewrite-sql` (accept sqlglot's rewrites of SQL text; off by default, so only layout changes), `-f`/`--script-encoding` (formerly `--encoding`, still accepted), and `--config`; `-` formats stdin to stdout. Also available as a [pre-commit hook](../guides/formatter.md) — the published hook defaults to `args: [--in-place]` so downstream consumers get formatting on commit without extra wiring. SQL reformatting (the optional sqlglot pass) requires the `[formatter]` extra as of 2.19.0; `--no-sql` works without it. |
 | `execsql lint`   | Static checks over files *and directories*, walking directories recursively for `*.sql`; `-` reads stdin. Scripts are read with `-f`/`--script-encoding` or `[encoding] script` from config, like `run`. Every issue carries a [rule code](../reference/lint.md#rules); `--select` / `--ignore` choose rules, `--output-format json` feeds tools, and `--statistics` counts issues per rule. It replaced the `--lint` flag, which checked only the one script it was given.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `execsql config` | List every config option with its current value, default, and the file that set it, resolved as a run would (pass a script to include its directory's `execsql.conf`). Passwords are masked. `--init` prints the template (replaces `--init-config`). `--validate` reports every problem in every config file a run reads, with file and line: invalid values and unparsable files as errors, unknown or misplaced sections and keys as warnings — upstream stopped at the first bad value and ignored unknown names silently.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `execsql list`   | `metacommands`, `encodings`, `plugins` or `keywords`, as text or JSON. Replaces `-m`, `-y`, `--list-plugins` and `--dump-keywords`; `-m` and `-y` are upstream flags and keep working as hidden aliases, deprecated when used without a command.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `execsql list`   | `metacommands`, `encodings`, `plugins` or `keywords`, as text or JSON. Replaces `-m`, `-y`, `--list-plugins` and `--dump-keywords`; `-m` and `-y` are upstream flags and keep working as hidden aliases, deprecated when used without a command. `-m` / `list metacommands` prints each metacommand's category and one-line summary (and its syntax when given a keyword) instead of upstream's listing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `execsql init`   | Set up a project: `execsql.conf` from the template, a script with a header (from the upstream script template), and the `execsql-format` / `execsql-lint` pre-commit hooks. Never overwrites without `--force`, and never rewrites an existing `.pre-commit-config.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `execsql lsp`    | A language server for editors, started over stdio: `execsql lint` findings shown as you type, with the `[lint]` settings of the workspace's config, completion of metacommands (as templates of their documented syntax), conditional tests, variables and export formats, hover explanations, navigation (definition, references, outline, `INCLUDE` links), Rename Symbol for variables, folding, quick fixes for P003, P004, V001 and P002, and Format Document (`execsql format` with the workspace's `[format]` settings). Settings are read per workspace folder and again when `execsql.conf` or an included file changes. The VS Code extension in `extras/vscode-execsql` starts it only in a trusted workspace. Needs the `lsp` extra (pygls). See [Editor Support](../guides/editors.md#editors).                                                                                                                                                                                                                                                                                                 |
 
 Formatter correctness notes added in the 2.19.x line:
 

{execsql2-2.26.0 → execsql2-2.27.0}/docs/dev/adding_metacommands.md

@@ -223,9 +223,32 @@ ______________________________________________________________________
 - [ ] Handler function added to the appropriate `src/execsql/metacommands/*.py` module
 - [ ] Handler imported in `src/execsql/metacommands/dispatch.py`
 - [ ] `mcl.add(...)` call added in `build_dispatch_table()` with `description=` and `category=`
+- [ ] Entry added to `src/execsql/metacommands/reference.py`: the syntax line(s) as the reference docs write them, a one-line summary and the docs anchor (see below)
+- [ ] A line using it added to `tests/data/lint/every_metacommand.sql`
 - [ ] Run `just install-vscode` to regenerate the VS Code grammar
 - [ ] Integration test added to `tests/test_metacommands.py` (or relevant file)
-- [ ] `pytest` passes locally (including `tests/test_registry.py` keyword consistency checks)
+- [ ] `pytest` passes locally (including `tests/test_registry.py` and `tests/test_reference.py`)
+
+### The readable syntax entry
+
+The dispatch table's regular expressions are not something to show a person.
+`execsql.metacommands.reference` holds what editors (`execsql lsp`) and
+`execsql list metacommands` show instead:
+
+```python
+Metacommand(
+    "MY_COMMAND",                       # the description= keyword
+    "action",                           # the category=
+    ("MY_COMMAND <table> TO <file>",),  # syntax lines, docs notation: <value>, [optional], A|B
+    "Does one thing to a table.",       # one sentence, at most 120 characters
+    "my_command",                       # the heading's anchor in docs/reference/metacommands.md
+),
+```
+
+Editor completion turns each syntax line into a fill-in template (`<value>`
+becomes a tab stop, `A|B` a choice). `tests/test_reference.py` fails until the
+entry exists, its anchor is a real heading, and each syntax line, filled with
+sample values, is accepted by the dispatch table.
 
 ______________________________________________________________________
 
@@ -251,3 +274,5 @@ mcl.add(
 ```
 
 The result is exposed as `CONDITIONAL_TABLE` and consumed at runtime via `_state.conditionallist`.
+
+Add a `Condition(...)` entry to `src/execsql/metacommands/reference.py` as well (name, syntax line such as `MY_TEST(<table>)`, one-line summary, docs anchor) and a use of it to `tests/data/lint/conditions_and_blocks.sql`; `tests/test_reference.py` checks that every conditional test has an entry.

{execsql2-2.26.0 → execsql2-2.27.0}/docs/dev/releasing.md

@@ -53,15 +53,16 @@ fails. Stay on the command until it exits.
 
 ### What runs on a tag push
 
-| Job                    | Gating?                            | Purpose                                                                           |
-| ---------------------- | ---------------------------------- | --------------------------------------------------------------------------------- |
-| `lint`                 | yes                                | ruff check + ruff format check                                                    |
-| `tests` (matrix)       | yes                                | py3.10–3.14 × {ubuntu, macos, windows}                                            |
-| `integration-tests`    | yes                                | PostgreSQL, MySQL, MSSQL service containers                                       |
-| `access-tests-windows` | yes (when Access install succeeds) | Real Access driver on `windows-latest`                                            |
-| `build`                | yes                                | Checks the tag equals `project.version`; `python -m build` produces sdist + wheel |
-| `publish`              | yes (tag-gated)                    | OIDC trusted-publisher PyPI upload                                                |
-| `generate-release`     | yes (tag-gated, after `publish`)   | Creates the GitHub release with auto-extracted CHANGELOG section                  |
+| Job                    | Gating?                                                 | Purpose                                                                                                 |
+| ---------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `lint`                 | yes                                                     | ruff check + ruff format check                                                                          |
+| `tests` (matrix)       | yes                                                     | py3.10–3.14 × {ubuntu, macos, windows}                                                                  |
+| `integration-tests`    | yes                                                     | PostgreSQL, MySQL, MSSQL service containers                                                             |
+| `access-tests-windows` | yes (when Access install succeeds)                      | Real Access driver on `windows-latest`                                                                  |
+| `build`                | yes                                                     | Checks the tag equals `project.version`; `python -m build` produces sdist + wheel                       |
+| `publish`              | yes (tag-gated)                                         | OIDC trusted-publisher PyPI upload                                                                      |
+| `vscode-extension`     | yes                                                     | Packages `extras/vscode-execsql` into `execsql-syntax.vsix` (on a tag, with the tag's X.Y.Z version)    |
+| `generate-release`     | yes (tag-gated, after `publish` and `vscode-extension`) | Creates the GitHub release with auto-extracted CHANGELOG section; attaches the sdist, wheel and `.vsix` |
 
 Publish / generate-release run only on tag refs
 (`if: startsWith(github.ref, 'refs/tags/v')`), so a non-bump push to
@@ -129,6 +130,6 @@ After `gh run watch` exits green:
 - `pip install execsql2==2.X.Y` in a throwaway venv — confirms the
     wheel landed on PyPI.
 - Browse the new GitHub release page; check the CHANGELOG section
-    matches what's on `main`.
+    matches what's on `main` and that `execsql-syntax.vsix` is attached.
 - `git pull` locally to retrieve the bump commit (you already had it
     locally if you bumped yourself, but other contributors will sync).

{execsql2-2.26.0 → execsql2-2.27.0}/docs/getting-started/installation.md

@@ -57,24 +57,25 @@ while that environment is active.
 
 Combine as many as you need in one install: `"execsql2[postgres,duckdb,formats]"`.
 
-| Extra            | Adds                                                            |
-| ---------------- | --------------------------------------------------------------- |
-| `postgres`       | PostgreSQL (psycopg)                                            |
-| `mysql`          | MySQL / MariaDB (pymysql)                                       |
-| `duckdb`         | DuckDB                                                          |
-| `mssql`          | MS SQL Server (pyodbc)                                          |
-| `odbc`           | Generic ODBC DSN (pyodbc)                                       |
-| `firebird`       | Firebird                                                        |
-| `oracle`         | Oracle (oracledb)                                               |
-| `formats`        | ODS, Excel, Jinja2, Feather/Parquet, HDF5, YAML                 |
-| `formatter`      | SQL reformatting for `execsql format` (sqlglot)                 |
-| `auth`           | OS keyring integration (desktop/native)                         |
-| `auth-plaintext` | Headless keyring (plaintext file backend)                       |
-| `auth-encrypted` | Headless keyring (encrypted file backend)                       |
-| `upsert`         | `PG_UPSERT` metacommand (pg-upsert)                             |
-| `map`            | `PROMPT MAP` widget (tkintermapview)                            |
-| `all-db`         | All database drivers                                            |
-| `all`            | Everything (all-db + formats + formatter + auth + upsert + map) |
+| Extra            | Adds                                                                         |
+| ---------------- | ---------------------------------------------------------------------------- |
+| `postgres`       | PostgreSQL (psycopg)                                                         |
+| `mysql`          | MySQL / MariaDB (pymysql)                                                    |
+| `duckdb`         | DuckDB                                                                       |
+| `mssql`          | MS SQL Server (pyodbc)                                                       |
+| `odbc`           | Generic ODBC DSN (pyodbc)                                                    |
+| `firebird`       | Firebird                                                                     |
+| `oracle`         | Oracle (oracledb)                                                            |
+| `formats`        | ODS, Excel, Jinja2, Feather/Parquet, HDF5, YAML                              |
+| `formatter`      | SQL reformatting for `execsql format` (sqlglot)                              |
+| `lsp`            | `execsql lsp`, the language server for editors (pygls; includes `formatter`) |
+| `auth`           | OS keyring integration (desktop/native)                                      |
+| `auth-plaintext` | Headless keyring (plaintext file backend)                                    |
+| `auth-encrypted` | Headless keyring (encrypted file backend)                                    |
+| `upsert`         | `PG_UPSERT` metacommand (pg-upsert)                                          |
+| `map`            | `PROMPT MAP` widget (tkintermapview)                                         |
+| `all-db`         | All database drivers                                                         |
+| `all`            | Everything (all-db + formats + formatter + auth + upsert + map + lsp)        |
 
 Some databases also need software outside Python, such as an ODBC driver or a
 client library. These are listed in the [Requirements](requirements.md#requirements) section.

{execsql2-2.26.0 → execsql2-2.27.0}/docs/getting-started/syntax.md

@@ -17,14 +17,15 @@ execsql list   metacommands|encodings|plugins|keywords [--output-format text|jso
 execsql init   [DIR] [--script NAME | --no-script] [--no-config] [--no-pre-commit] [--force]
 ```
 
-| Command  | Purpose                                                                                    |
-| -------- | ------------------------------------------------------------------------------------------ |
-| `run`    | Execute a script against a database.                                                       |
-| `format` | Normalize metacommand keywords, block indentation, and SQL layout.                         |
-| `lint`   | Static analysis without a database. Exits 1 when any error is found.                       |
-| `config` | List every config option with its value, default and source; `--init` prints the template. |
-| `list`   | Print metacommands, encoding names, installed plugins, or the full keyword vocabulary.     |
-| `init`   | Set up a project: `execsql.conf`, a script with a header, and the pre-commit hooks.        |
+| Command  | Purpose                                                                                                 |
+| -------- | ------------------------------------------------------------------------------------------------------- |
+| `run`    | Execute a script against a database.                                                                    |
+| `format` | Normalize metacommand keywords, block indentation, and SQL layout.                                      |
+| `lint`   | Static analysis without a database. Exits 1 when any error is found.                                    |
+| `config` | List every config option with its value, default and source; `--init` prints the template.              |
+| `list`   | Print metacommands, encoding names, installed plugins, or the full keyword vocabulary.                  |
+| `init`   | Set up a project: `execsql.conf`, a script with a header, and the pre-commit hooks.                     |
+| `lsp`    | The language server editors start for `.sql` files; see [Editor Support](../guides/editors.md#editors). |
 
 `format` and `lint` accept files or directories; directories are searched
 recursively for `*.sql`, and `-` reads one script from stdin. A CI job runs them
@@ -133,14 +134,15 @@ alone exit `0`. With `--output-format json` it prints
 
 ```text
 execsql list metacommands|encodings|plugins|keywords [--output-format text|json]
+execsql list metacommands [KEYWORD] [--output-format text|json]
 ```
 
-| Command        | Prints                                                                                                                        |
-| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `metacommands` | Every metacommand and its syntax.                                                                                             |
-| `encodings`    | Every character encoding name accepted by `-e`, `-f`, `-g` and `-i`.                                                          |
-| `plugins`      | Installed plugins: metacommands, exporters, importers. See [Plugin System](../dev/architecture.md#plugin-system).             |
-| `keywords`     | The full vocabulary: metacommands by category, conditions, CONFIG options, export formats, database types, variable patterns. |
+| Command        | Prints                                                                                                                                                                                      |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `metacommands` | Every metacommand with its category and a one-line summary. With a keyword (`execsql list metacommands export query`), that metacommand's syntax lines and a link to its reference section. |
+| `encodings`    | Every character encoding name accepted by `-e`, `-f`, `-g` and `-i`.                                                                                                                        |
+| `plugins`      | Installed plugins: metacommands, exporters, importers. See [Plugin System](../dev/architecture.md#plugin-system).                                                                           |
+| `keywords`     | The full vocabulary: metacommands by category, conditions, CONFIG options, export formats, database types, variable patterns.                                                               |
 
 Each list is its own command, `execsql list keywords --help` included. With
 `--output-format json`, `keywords` prints the JSON that editor tooling such as