inline-sql-toolkit 0.4.7

package/README.md

@@ -0,0 +1,224 @@
+# Inline SQL Toolkit
+
+Inline SQL Toolkit highlights SQL embedded in Python strings and formats selected
+SQL with the bundled `sql-formatter` layout engine. It supports ordinary `.py`
+files, marimo
+(`.mo.py`) programs, and Python cells in Jupyter notebooks. In marimo notebooks
+the `python` and `mo-python` cell languages are supported. SQL-language cells
+and notebook magic commands (`%sql`, `%%sql`, and similar magic syntax) are not
+supported.
+
+Requirements are VS Code 1.95 or newer. Formatting is
+manual-only: this extension does not register a formatter provider, format on
+save, format on type, or format ranges automatically. The accompanying CLI is
+likewise an explicit invocation, not an automated background formatter. It never
+executes SQL, validates SQL, infers a SQL dialect, connects to a database, or
+sends source to the network. The formatter is best-effort; an unsafe candidate is
+skipped while other safe candidates may still be edited.
+
+In short, SQL is never executed by this extension. SQL is never validated by
+this extension.
+
+## Architecture
+
+[![Inline SQL Toolkit architecture](inline-sql-toolkit-architecture.png)](https://hidenobunagai.github.io/inline-sql-toolkit/)
+
+[Open the interactive architecture diagram (HTML)](https://hidenobunagai.github.io/inline-sql-toolkit/)
+
+## Quick start
+
+Open a supported Python document or notebook cell, place the cursor in one of
+the examples below, and choose a command from the Command Palette.
+
+### Plain string
+
+```python
+query = "SELECT id, name FROM users WHERE active = true"
+```
+
+### Marker triple-quoted string
+
+```python
+query = """--sql
+select id, name
+from users
+where active = true
+"""
+```
+
+Formatting keeps the `--sql` marker directly after the opening quote, indents
+the SQL one level below the literal's base indent, and aligns the closing
+triple quote with the base indent:
+
+```python
+query = """--sql
+  select id, name
+  from users
+  where active = true
+"""
+```
+
+A marker on its own line is normalized to the opening quote, so both styles
+produce the same output. With the default `keywordCase: upper`, keywords are
+uppercased.
+
+### Complex f-string
+
+```python
+account_id = get_account_id()
+query = f"""--sql
+SELECT id, name
+FROM users
+WHERE account_id = {account_id}
+  AND status = {{'active'}}
+"""
+```
+
+The f-string example demonstrates that Python replacement fields and escaped
+braces remain Python source. Only the SQL portions are considered for layout;
+the extension preserves the original f-string expressions and escapes.
+
+## Commands
+
+The command IDs are shown for keybindings and automation integrations:
+
+- **Inline SQL: Format at Cursor** (`inlineSql.formatAtCursor`) formats the SQL
+  candidate containing the cursor.
+- **Inline SQL: Format Selection** (`inlineSql.formatSelection`) formats SQL
+  candidates intersecting the current selection.
+- **Inline SQL: Format All** (`inlineSql.formatAll`) formats every detected
+  candidate in the current document or notebook cell.
+
+Each invocation checks the document version and the expected source text before
+creating one `WorkspaceEdit`, so the operation is one undo step. VS Code does
+not provide an atomic, versioned precondition for an edit that happens after
+that check. Changes observed before the edit are rejected as stale; a change
+that races after the check can still be applied because VS Code provides no
+later atomic precondition.
+
+## Settings
+
+- `inlineSql.format.keywordCase`: `upper` (default), `lower`, or `preserve`.
+- `inlineSql.format.indentWidth`: SQL indentation width from 1 to 8 spaces
+  (default 2).
+- `inlineSql.format.wrapAfter`: preferred line width from 20 to 500 (default
+  88).
+- `inlineSql.format.useSpaceAroundOperators`: add spaces around operators
+  (default `true`).
+- `inlineSql.format.replaceOrdinals`: replace `GROUP BY` / `ORDER BY` ordinal
+  numbers (`1`, `2`, ...) with the referenced column names, preferring
+  aliases (default `true`).
+- `inlineSql.format.dialect`: SQL dialect used by the formatter (`sql`,
+  `mysql`, `postgresql`, or `sqlite`; default `postgresql`).
+
+The extension highlights inline SQL with an injected TextMate grammar: SQL
+strings that start with `-- sql` (or a leading SQL keyword) are embedded as
+`meta.embedded.sql` and colored with the theme's SQL rules. The grammar follows
+the same approach as the popular `inline-sql-syntax` extension and works in
+plain files and notebook cells alike. Because the highlighting is grammar-based,
+a language server's semantic tokens can override it; if SQL highlighting
+disappears, disable semantic highlighting for the language server
+(`editor.semanticHighlighting.enabled: false`) or for the server itself.
+
+## Command line (CLI)
+
+The `inline-sql-toolkit` command-line tool formats Python files or standard input using the exact same formatting engine and safety checks as the VS Code extension's **Format All** command. Unsafe candidates (such as invalid Python syntax, unsupported literals, or unparseable f-strings) are skipped rather than producing corrupt output.
+
+Run directly via `npx` or install with `bun add -d inline-sql-toolkit` (or `npm install -D inline-sql-toolkit`):
+
+```bash
+npx inline-sql-toolkit [options] [files...]
+```
+
+When run without file arguments, the CLI reads Python source from standard input and prints the formatted result to standard output. Notebook files (`.ipynb`) are not supported by the CLI; use the VS Code extension for Jupyter and marimo notebook cell formatting. The CLI supports standard Python source files (`.py`, `.mo.py`) and stdin.
+
+### CLI Options
+
+| Option                        | Description                                                       | Default                    |
+| ----------------------------- | ----------------------------------------------------------------- | -------------------------- |
+| `-w, --write`                 | Rewrite files in place (no write if unchanged)                    | off                        |
+| `--check`                     | Exit with code 1 if any file would change                         | off                        |
+| `--dialect <name>`            | SQL dialect: `sql`, `mysql`, `postgresql`, or `sqlite`            | `postgresql`               |
+| `--keyword-case <case>`       | Case for SQL keywords: `upper`, `lower`, or `preserve`            | `upper`                    |
+| `--indent-width <1-8>`        | SQL indentation width in spaces                                   | `2`                        |
+| `--wrap-after <20-500>`       | Preferred expression line width                                   | `88`                       |
+| `--no-space-around-operators` | Keep dense operators                                              | spaced                     |
+| `--no-ordinals`               | Do not replace `GROUP BY` / `ORDER BY` ordinals with column names | replace                    |
+| `-c, --config <file>`         | Configuration JSON file                                           | Nearest `.inline-sql.json` |
+| `-h, --help`                  | Show usage help                                                   |                            |
+| `--version`                   | Show version number                                               |                            |
+
+Exit codes: `0` on success, `1` when `--check` finds unformatted files, and `2` on usage, configuration, I/O, or formatting errors.
+
+### Configuration file (`.inline-sql.json`)
+
+The CLI automatically searches for a `.inline-sql.json` file in the current working directory and its parent directories. The configuration structure matches VS Code settings:
+
+```json
+{
+  "format": {
+    "keywordCase": "upper",
+    "indentWidth": 2,
+    "wrapAfter": 88,
+    "useSpaceAroundOperators": true,
+    "replaceOrdinals": true,
+    "dialect": "postgresql"
+  }
+}
+```
+
+Precedence order is **CLI flags > configuration file > default values**.
+
+## Detection and supported syntax
+
+Formatter detection is source-level: it examines Python tokens and the literal
+characters in the source, rather than evaluating the string value. A candidate
+is found when either condition holds:
+
+1. The first logical, non-blank line starts with `-- sql` or `--sql` after
+   horizontal whitespace. Matching is case-insensitive and the marker text is
+   preserved. On format, a marker on its own line moves to sit directly after
+   the opening quote (`"""--sql`), so both input styles produce one output.
+2. After removing only physically present ASCII space, tab, CR, and LF
+   characters, the source starts with one of `SELECT`, `WITH`, `INSERT`,
+   `UPDATE`, `DELETE`, `MERGE`, `CREATE`, `ALTER`, `DROP`, `TRUNCATE`, or
+   `EXPLAIN`, followed by a word boundary. The two source characters `\n` are
+   not treated as whitespace.
+
+Standalone plain and raw strings, f-strings, and raw f-strings (`f`, `rf`, and
+`fr`, in either case) are supported with single, double, and triple delimiters
+(`'`, `"`, `'''`, and `"""`). A parseable candidate in a supported literal is
+also the candidate used by the syntax highlighting grammar.
+
+The following are intentionally skipped: bytes and byte strings (`b`/`rb`),
+implicit or explicit string concatenation, t-strings, invalid Python, dynamic
+or non-literal SQL, and SQL-language cells. A candidate that cannot be restored
+without changing Python source is reported as unsafe and is not edited.
+
+## Trust, privacy, and offline behavior
+
+In an untrusted workspace the extension provides highlighting only. The three
+formatting commands remain visible, but formatting is disabled: no analysis
+runs, no Code Actions are offered, and no edits are applied until the
+workspace is trusted. SQL is not written to disk, logged, telemetered, sent
+over the network, passed to a shell/database, or executed. The bundled
+`sql-formatter` code runs offline and is a layout engine, not a SQL validator.
+
+## Troubleshooting
+
+- **No candidate found:** confirm the source uses a supported literal and that
+  the first logical line has `-- sql`/`--sql`, or that a listed keyword is at
+  the source-level start with a word boundary.
+- **Unsupported literal or unsafe f-string:** remove concatenation, bytes or
+  t-string syntax, and verify that Python parses the document. Complex f-string
+  expressions are skipped when their source spans cannot be restored exactly.
+- **Formatting is unavailable:** use a trusted workspace and check the
+  diagnostic reason shown by the extension (`WORKSPACE_UNTRUSTED`,
+  `INVALID_CONFIGURATION`, or `PROCESS_FAILED`).
+- **SQL looks different than expected:** formatting does not validate SQL or
+  infer a dialect. Adjust the settings above and review the source-level
+  candidate before applying the one-step edit.
+
+For security reporting, see [SECURITY.md](SECURITY.md). For source-free bug
+reports and diagnostic reason codes, see [SUPPORT.md](SUPPORT.md). Licensing and
+component provenance are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/SECURITY.md

@@ -0,0 +1,29 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are assessed against the latest published release. Use the
+newest version before reporting a vulnerability; older versions may no longer
+receive fixes. The current version is listed in the changelog.
+
+## Private reporting
+
+Please do not disclose security vulnerabilities in public issues, discussions,
+or pull requests. Report privately through the repository's configured GitHub
+security advisory UI: **Security → Advisories → Report a vulnerability**. This
+policy intentionally does not publish an email address or invent another
+contact channel.
+
+Include the affected version, the smallest reproducible description, impact,
+and any relevant configuration. Do not include credentials, tokens, customer
+data, private source, or other secrets. If source is necessary to reproduce the
+issue, redact it and describe only the smallest safe shape.
+
+## Security boundaries
+
+Inline SQL Toolkit is designed to work offline. It does not execute SQL,
+connect to a database, make network requests, run a shell command, collect
+telemetry, or format automatically. In an untrusted workspace it provides
+highlighting only. In a trusted workspace the extension formats the detected
+SQL in-process with the bundled `sql-formatter` layout engine; document text is
+not written to disk or emitted in logs.

package/SUPPORT.md

@@ -0,0 +1,43 @@
+# Support
+
+Use a repository issue for usage questions and reproducible, non-sensitive
+bugs. This project has no guaranteed response time. Do not include SQL source,
+credentials, tokens, customer data, private paths, or other secrets. Reports
+should be source-free: describe the literal shape (for example, plain,
+triple-quoted, or f-string), operation, document/cell kind, and redacted
+settings instead of pasting a query.
+
+Include these diagnostic details when available:
+
+- Inline SQL Toolkit version (for example, `0.1.0`), VS Code version, and
+  operating system.
+- Whether the workspace is trusted, and whether the target is a `.py`, Jupyter
+  Python cell, or marimo `python`/`mo-python` cell.
+- The command (`inlineSql.formatAtCursor`, `inlineSql.formatSelection`, or
+  `inlineSql.formatAll`), whether the cursor/selection was involved, and the
+  relevant non-sensitive setting names and values.
+- The diagnostic reason code shown by the extension. Never include document
+  contents merely to provide a reason code.
+
+## Diagnostic reason codes
+
+| Code                      | Meaning                                                 |
+| ------------------------- | ------------------------------------------------------- |
+| `WORKSPACE_UNTRUSTED`     | Formatting is disabled until trust is granted.          |
+| `INVALID_CONFIGURATION`   | An `inlineSql.format.*` setting has an invalid value.   |
+| `NO_SQL_CANDIDATE`        | No supported source-level SQL candidate was found.      |
+| `UNSUPPORTED_LITERAL`     | The literal shape is outside the supported scope.       |
+| `UNSAFE_FSTRING_RESTORE`  | An f-string could not be restored byte-for-byte safely. |
+| `UNSAFE_RAW_STRING`       | A raw-string edit could not preserve its source safely. |
+| `FORMATTER_FAILED`        | The bundled formatter could not produce a safe result.  |
+| `RESOURCE_LIMIT_EXCEEDED` | A document, candidate, or request exceeded a guard.     |
+| `PROCESS_CANCELLED`       | The formatting request was cancelled.                   |
+| `PROCESS_FAILED`          | Formatting failed unexpectedly.                         |
+| `DOCUMENT_CHANGED`        | The document changed before the guarded edit.           |
+| `APPLY_EDIT_FAILED`       | VS Code rejected the guarded workspace edit.            |
+| `PROTOCOL_ERROR`          | The result failed an internal consistency check.        |
+
+Inline SQL Toolkit does not provide database connectivity, SQL validation,
+network services, or telemetry. A support report should therefore focus on the
+source shape, operation, versions, trust state, and reason code rather than a
+database or remote service.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,56 @@
+# Third-party notices
+
+Inline SQL Toolkit includes the third-party components below. Their authors and
+copyright holders retain their rights; this project does not claim ownership of
+their source or license text. Copies of the required notices are packaged in
+the VSIX under `third_party/`.
+
+## `inline-sql-syntax` grammar (highlight-sql-string.json)
+
+The injected TextMate grammar in `syntaxes/inline-sql.tmLanguage.json` is
+derived from the `highlight-sql-string.json` grammar of the
+`inline-sql-syntax` extension (MIT license). Exact provenance:
+
+- Marketplace: <https://marketplace.visualstudio.com/items?itemName=qufiwefefwoyn.inline-sql-syntax>
+- Source repository: <https://github.com/barklan/inline_sql_syntax>
+- License: MIT, Copyright (c) 2021 Gleb Buzin
+
+The complete MIT license and the upstream grammar file are in
+[`third_party/inline-sql-syntax/`](third_party/inline-sql-syntax/) and are
+copied into the packaged VSIX.
+
+## `sql-formatter` npm package (v15.8.2)
+
+The formatter engine is the `sql-formatter` package (MIT license). esbuild
+inlines it into `dist/extension.js` and `dist/cli.js`, so no `node_modules` tree
+is packaged and the license text has to travel with the bundle. Exact provenance:
+
+- Package: <https://www.npmjs.com/package/sql-formatter/v/15.8.2>
+- Source repository: <https://github.com/sql-formatter-org/sql-formatter>
+- License: MIT, Copyright (c) 2016-2020 ZeroTurnaround LLC, Copyright (c)
+  2020-2021 George Leslie-Waksman and other contributors, Copyright (c)
+  2021-Present inferrinizzard and other contributors
+
+The complete MIT license is in
+[`third_party/sql-formatter/`](third_party/sql-formatter/) and is copied into
+the packaged VSIX.
+
+## `nearley` npm package (v2.20.1)
+
+`sql-formatter` builds its SQL parser on the `nearley` package (MIT license).
+esbuild inlines `nearley` into `dist/extension.js` and `dist/cli.js` as well.
+Exact provenance:
+
+- Package: <https://www.npmjs.com/package/nearley/v/2.20.1>
+- Source repository: <https://github.com/hardmath123/nearley>
+- License: MIT, Copyright (c) 2014, 2015, 2016, 2017, 2018, 2019 Kartik
+  Chandra, Tim Radvan
+
+The complete MIT license is in [`third_party/nearley/`](third_party/nearley/)
+and is copied into the packaged VSIX.
+
+## Project license
+
+The Inline SQL Toolkit source and original documentation are provided under the
+MIT license in [`LICENSE`](LICENSE). This project license does not replace or
+alter the third-party licenses above.