inline-sql-toolkit 0.5.2 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.5.3 - 2026-10-10
+
+- Feature: a "# inline-sql: skip" comment excludes a specific SQL literal from formatting (as a trailing comment on the closing quote line or on a dedicated line directly preceding the literal).
+
 ## 0.5.2 - 2026-10-09
 
 - Fixed: with `inlineSql.format.commaPosition: "before"`, the rest of a

package/README.md

@@ -246,6 +246,41 @@ order, or the candidate is skipped (`FORMATTER_FAILED`).
 A single-quoted literal stays on one line and keeps its leading and trailing
 spaces, because the string may be joined to other text at runtime.
 
+### Skipping a literal
+
+To exclude a specific SQL literal from formatting, add an `# inline-sql: skip` pragma comment (case-insensitive, matched with `/\binline-sql:\s*skip(?![\w-])/i`). Other comments such as `# noqa: E501` or `# type: ignore` may share the same comment line.
+
+You can place the pragma in either of two ways:
+
+1. **Trailing comment on the closing line**: on the line where the literal ends (the closing quote line).
+   ```python
+   q = "select a,b from t"  # inline-sql: skip
+   q = """--sql
+   select   a,
+            b
+   from t
+   """  # inline-sql: skip
+   ```
+2. **Dedicated comment line immediately preceding the literal**: on the line directly above where the literal starts, containing only whitespace followed by the `# inline-sql: skip` comment.
+   ```python
+   # inline-sql: skip
+   q = """--sql
+   ...
+   """
+   query = (
+       # inline-sql: skip
+       """--sql ..."""
+   )
+   ```
+
+Notes on skipping behavior:
+
+- On triple-quoted strings, any text after the opening quotes (such as `"""--sql # inline-sql: skip`) is part of the string body, not a Python comment, so a pragma placed there has no effect.
+- A trailing comment on a preceding statement (e.g. `a = "select 1"  # inline-sql: skip`) does not affect a literal starting on the next line (`b = "select 2"`). Dedicated comment lines must consist only of whitespace and the comment.
+- Syntax highlighting is powered by TextMate grammar and is not affected by `# inline-sql: skip`. Only formatting excludes the literal.
+- When running **Format at Cursor** on a skipped literal, the command reports `NO_SQL_CANDIDATE`.
+- Both CLI `--check` and `--write` honor `# inline-sql: skip` with the exact same rules: skipped literals are never formatted, never reported on stderr as skipped candidates, and do not cause `--check` to fail.
+
 ## Trust, privacy, and offline behavior
 
 In an untrusted workspace the extension provides highlighting only. The three
@@ -268,7 +303,8 @@ over the network, passed to a shell/database, or executed. The bundled
   `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.
+  candidate before applying the one-step edit, or exclude the literal with
+  `# inline-sql: skip`.
 
 For security reporting, see [SECURITY.md](SECURITY.md). For source-free bug
 reports and diagnostic reason codes, see [SUPPORT.md](SUPPORT.md). Licensing and

package/dist/cli.js

@@ -808,6 +808,7 @@ function stringSurfaceAt(source, index) {
 }
 function scanSource(source) {
   const surfaces = [];
+  const comments = [];
   let unterminated = false;
   let index = 0;
   while (index < source.length) {
@@ -818,6 +819,7 @@ function scanSource(source) {
     }
     if (char === "#") {
       const end = source.indexOf("\n", index);
+      comments.push(new SourceSpan(index, end === -1 ? source.length : end));
       index = end === -1 ? source.length : end;
       continue;
     }
@@ -837,7 +839,7 @@ function scanSource(source) {
     }
     index++;
   }
-  return { surfaces, unterminated };
+  return { surfaces, comments, unterminated };
 }
 function scanFstringFields(source, contentSpan) {
   const fields = [];
@@ -919,6 +921,7 @@ function fstringKind(prefix) {
 }
 
 // src/python-analysis/literals.ts
+var SKIP_PRAGMA = /\binline-sql:\s*skip(?![\w-])/i;
 function onlyWhitespace(text) {
   return /^[\s]*$/.test(text);
 }
@@ -941,7 +944,25 @@ function isConcatenated(source, surfaces, index) {
 }
 function analyzeDocument(source) {
   const sourceMap = SourceMap.fromText(source);
-  const { surfaces, unterminated } = scanSource(source);
+  const { surfaces, comments, unterminated } = scanSource(source);
+  const trailingPragmas = /* @__PURE__ */ new Set();
+  const ownLinePragmas = /* @__PURE__ */ new Set();
+  for (const span of comments) {
+    const commentText2 = source.slice(span.start, span.end);
+    if (!SKIP_PRAGMA.test(commentText2)) continue;
+    const line = sourceMap.vscodeFromOffset(span.start).line;
+    const lineStartOffset = sourceMap.offsetFromVscode(line, 0);
+    const prefix = source.slice(lineStartOffset, span.start);
+    if (/^[ \t]*$/.test(prefix)) {
+      ownLinePragmas.add(line);
+    } else {
+      trailingPragmas.add(line);
+    }
+  }
+  const skipPragmaLines = {
+    trailing: trailingPragmas,
+    ownLine: ownLinePragmas
+  };
   const supported = [];
   const unsupported = [];
   surfaces.forEach((surface, index) => {
@@ -1005,7 +1026,8 @@ function analyzeDocument(source) {
     sourceMap,
     unterminated,
     supported: [...supported].sort((left, right) => left.span.start - right.span.start),
-    unsupported: [...unsupported].sort((left, right) => left.span.start - right.span.start)
+    unsupported: [...unsupported].sort((left, right) => left.span.start - right.span.start),
+    skipPragmaLines
   };
 }
 
@@ -2211,6 +2233,12 @@ var MAX_CANDIDATE_BYTES = 1024 * 1024;
 var MAX_CANDIDATES = 1e3;
 var ResourceLimitError = class extends Error {
 };
+function isSkippedByPragma(literal, analysis) {
+  const startLine = analysis.sourceMap.vscodeFromOffset(literal.span.start).line;
+  const endLine = analysis.sourceMap.vscodeFromOffset(literal.span.end).line;
+  const { trailing, ownLine } = analysis.skipPragmaLines;
+  return ownLine.has(startLine - 1) || trailing.has(endLine) || ownLine.has(endLine);
+}
 function discover(analysis) {
   const literals = [
     ...analysis.supported,
@@ -2219,7 +2247,7 @@ function discover(analysis) {
   const units = literals.map((literal) => ({
     literal,
     detection: detectSql(literal, analysis.sourceMap)
-  })).filter((unit) => unit.detection.matched);
+  })).filter((unit) => unit.detection.matched && !isSkippedByPragma(unit.literal, analysis));
   return [...units].sort((left, right) => left.literal.span.start - right.literal.span.start);
 }
 function selectUnits(units, target, sourceMap) {

package/package.json

@@ -11,7 +11,7 @@
   "bugs": {
     "url": "https://github.com/hidenobunagai/inline-sql-toolkit/issues"
   },
-  "version": "0.5.2",
+  "version": "0.5.3",
   "icon": "icon.png",
   "type": "module",
   "bin": {