inline-sql-toolkit 0.5.1 → 0.5.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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
+  multi-line item (`CASE … END`, a subquery, a wrapped function call) now
+  moves right with its leading `, `, so `END` and the closing `)` no longer
+  line up with the comma. Only lines up to the `)` / `]` / `END` that closes
+  the item move; a following `JOIN` or statement stays put. Nested items add
+  up; lines that continue a string or block comment are left untouched.
+
 ## 0.5.1 - 2026-10-02
 
 - Security: pins patched versions of OSV-flagged transitive dependencies

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
   };
 }
 
@@ -1907,8 +1929,9 @@ function wrappingComma(line) {
   if (comma < 0) return -1;
   return /^[ \t]*(?:--.*)?$/.test(line.slice(comma + 1)) ? comma : -1;
 }
-function moveCommasToLineStarts(text) {
+function moveCommasToLineStarts(text, dialect) {
   const lines = text.split("\n");
+  const inserts = /* @__PURE__ */ new Map();
   for (let index = 0; index + 1 < lines.length; index++) {
     const line = lines[index] ?? "";
     const next = lines[index + 1] ?? "";
@@ -1920,8 +1943,43 @@ function moveCommasToLineStarts(text) {
     const content = nextParts?.[2] ?? "";
     lines[index] = `${line.slice(0, comma)}${line.slice(comma + 1)}`.trimEnd();
     lines[index + 1] = `${indent}, ${content}`;
+    inserts.set(index + 1, indent.length);
+  }
+  if (inserts.size === 0) return text;
+  return shiftMovedItems(lines, inserts, dialect).join("\n");
+}
+function shiftMovedItems(lines, inserts, dialect) {
+  const starts = [];
+  let offset = 0;
+  for (const line of lines) {
+    starts.push(offset);
+    offset += line.length + 1;
+  }
+  const tokens = lexSql(lines.join("\n"), dialect);
+  const textLines = /* @__PURE__ */ new Set();
+  for (const token of tokens) {
+    if (token.kind === "space" || !token.text.includes("\n")) continue;
+    starts.forEach((start, line) => {
+      if (start > token.start && start < token.end) textLines.add(line);
+    });
+  }
+  const shifts = new Array(lines.length).fill(0);
+  for (const [target, column] of inserts) {
+    for (let index = target + 1; index < lines.length; index++) {
+      const line = lines[index] ?? "";
+      const indent = line.length - line.trimStart().length;
+      if (indent === line.length || textLines.has(index)) continue;
+      if (indent < column) break;
+      if (indent === column && !/^(?:[)\]]|END\b)/i.test(line.slice(indent))) break;
+      shifts[index] = (shifts[index] ?? 0) + 2;
+    }
   }
-  return lines.join("\n");
+  return lines.map((line, index) => {
+    const shift = shifts[index] ?? 0;
+    if (shift === 0) return line;
+    const indent = line.length - line.trimStart().length;
+    return `${line.slice(0, indent)}${" ".repeat(shift)}${line.slice(indent)}`;
+  });
 }
 var DOLLAR_QUOTE = /\$[A-Za-z_][A-Za-z0-9_]*\$|\$\$/y;
 function rejoinFunctionCalls(text) {
@@ -2047,7 +2105,7 @@ function formatOnce(analysis, literal, detection, options, nonce, sqlFormatter,
     formatted = rejoinFunctionCalls(formatted);
   }
   if (options.commaPosition === "before") {
-    formatted = moveCommasToLineStarts(formatted);
+    formatted = moveCommasToLineStarts(formatted, options.dialect);
   }
   formatted = breakTrailingDistributeLines(formatted, options.dialect);
   const difference = sqlTokenDifference(plan.protectedSql, formatted, options.dialect);
@@ -2175,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,
@@ -2183,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.1",
+  "version": "0.5.3",
   "icon": "icon.png",
   "type": "module",
   "bin": {