@codacy/tools-sqlint-0 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codacy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# @codacy/tools-sqlint-0
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Updating patterns](#updating-patterns)
+- [Updating the SQLint version](#updating-the-sqlint-version)
+- [Development](#development)
+- [Notes for maintainers](#notes-for-maintainers)
+
+---
+
+## Overview
+
+SQL syntax checker using the [SQLint](https://github.com/purcell/sqlint) Ruby gem. Uses the CLI execution strategy -- spawns `sqlint` via `spawnTool()` and parses its text output.
+
+| Property      | Value                                  |
+| ------------- | -------------------------------------- |
+| Tool ID       | `SQLint`                               |
+| Codacy UUID   | `25b6766b-06c6-4625-9df1-561d28386b5f` |
+| Strategy      | CLI                                    |
+| Languages     | SQL, PLSQL                             |
+| Binary        | `sqlint` (installed via `gem install`) |
+| File patterns | `**/*.sql`                             |
+
+## Updating patterns
+
+```bash
+# Re-fetch pattern metadata from the Codacy API
+pnpm prefetch
+
+# Commit the result
+git add src/patterns.json
+```
+
+The `prefetch` script calls `packages/tools/scripts/fetch-patterns.mjs` with the tool UUID to download pattern metadata from the Codacy API.
+
+SQLint has a single umbrella pattern: `SQLint_allIssues`. All syntax errors map to this one pattern.
+
+## Updating the SQLint version
+
+1. Update `SQLINT_VERSION` in `src/adapter.ts`
+2. Run `pnpm prefetch` to check for any changes
+3. Run `pnpm test` to verify compatibility
+4. If the major version changes, create a new adapter package (`sqlint-1/`)
+
+## Development
+
+```bash
+pnpm build    # Build with tsup
+pnpm test     # Run tests (requires ruby + sqlint in PATH for integration tests)
+```
+
+To install sqlint locally for testing:
+
+```bash
+gem install sqlint
+```
+
+## Notes for maintainers
+
+- **PostgreSQL-only**: SQLint uses `pg_query` (libpg_query) under the hood, which means it only validates PostgreSQL dialect SQL. Non-PostgreSQL syntax may produce false positives.
+- **Ruby gem dependency**: SQLint requires Ruby >= 2.7 as a runtime. The adapter uses `ensureRuby()` to download a portable Ruby if no system Ruby is found.
+- **Native compilation**: The `pg_query` gem includes a native C extension that compiles libpg_query during installation. A C compiler (gcc/clang) and make are required on the system.
+- Gems are installed in an isolated directory at `~/.codacy/runtimes/sqlint-0/gems/` via `GEM_HOME`/`GEM_PATH` environment variables.
+- Output format is plain text, one finding per line: `file.sql:line:column:SEVERITY message`.
+- Exit codes: 0 = no errors, 1 = errors found (both are success states for the adapter).
+- SQLint has no configuration files -- it always checks all syntax.
+- All findings map to the single umbrella pattern `SQLint_allIssues`.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import * as _codacy_tooling from '@codacy/tooling';
+
+declare const _default: Readonly<_codacy_tooling.ToolAdapter>;
+
+export { _default as default };

package/dist/index.js

@@ -0,0 +1,388 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var import_tooling2 = require("@codacy/tooling");
+
+// src/adapter.ts
+var import_tooling = require("@codacy/tooling");
+var import_path = __toESM(require("path"));
+var import_promises = __toESM(require("fs/promises"));
+
+// src/patterns.json
+var patterns_default = [
+  {
+    id: "SQLint_allIssues",
+    category: "Compatibility",
+    severityLevel: "High",
+    title: "Enforce ANSI SQL Syntax Compliance",
+    enabled: true,
+    parameters: []
+  }
+];
+
+// src/adapter.ts
+var TOOL_ID = "SQLint";
+var ADAPTER_ID = "sqlint-0";
+var SQLINT_VERSION = "0.2.1";
+var RUBY_VERSION_RANGE = ">=2.7.0";
+var PATTERN_META = new Map(
+  patterns_default.map((p) => [
+    p.id,
+    {
+      category: p.category,
+      severity: p.severityLevel ?? "Info"
+    }
+  ])
+);
+var UMBRELLA_PATTERN = "SQLint_allIssues";
+function ruleMetadata() {
+  return PATTERN_META.get(UMBRELLA_PATTERN) ?? { category: "Compatibility", severity: "High" };
+}
+var OUTPUT_LINE_REGEX = /^(.+?):(\d+):(\d+):(ERROR|WARNING)\s+(.+)$/;
+function getLineContent(lines, lineNumber) {
+  return lines[lineNumber - 1] ?? "";
+}
+async function readFileLines(filePath) {
+  try {
+    const content = await import_promises.default.readFile(filePath, "utf-8");
+    return content.split("\n");
+  } catch {
+    return [];
+  }
+}
+function buildResult(startedAt, completedAt, issues, errors, filesAnalyzed) {
+  const durationMs = completedAt.getTime() - startedAt.getTime();
+  return {
+    metadata: {
+      startedAt: startedAt.toISOString(),
+      completedAt: completedAt.toISOString(),
+      durationMs
+    },
+    issues,
+    errors,
+    summary: {
+      toolId: TOOL_ID,
+      status: errors.some((e) => e.level === "error") ? "partial" : "success",
+      issueCount: issues.length,
+      errorCount: errors.length,
+      durationMs,
+      filesAnalyzed
+    }
+  };
+}
+async function resolveToolInvocation(ctx) {
+  const gemPaths = (0, import_tooling.getGemPaths)(ctx.globalDir, ADAPTER_ID);
+  const scriptPath = (0, import_tooling.resolveGemBinary)(gemPaths, "sqlint");
+  const portableRubyBin = (0, import_tooling.resolvePortableRubyBinary)(ctx.globalDir, "3.2.11");
+  try {
+    await import_promises.default.access(portableRubyBin);
+    await import_promises.default.access(scriptPath);
+    return { binary: portableRubyBin, prefixArgs: [scriptPath], rubyPath: portableRubyBin };
+  } catch {
+  }
+  const rubyInfo = await (0, import_tooling.findRuby)(RUBY_VERSION_RANGE).catch(() => null);
+  try {
+    await import_promises.default.access(scriptPath);
+    return {
+      binary: scriptPath,
+      prefixArgs: [],
+      rubyPath: rubyInfo?.path
+    };
+  } catch {
+  }
+  return { binary: "sqlint", prefixArgs: [], rubyPath: rubyInfo?.path };
+}
+var adapter = {
+  id: TOOL_ID,
+  displayName: "SQLint",
+  preferredVersion: SQLINT_VERSION,
+  compatibleVersions: ">=0.2.0",
+  website: "https://github.com/purcell/sqlint",
+  languages: ["SQL", "PLSQL"],
+  filePatterns: ["**/*.sql"],
+  supportedOS: ["linux", "darwin"],
+  supportedArch: ["x64", "arm64"],
+  supportedRunners: ["local", "container"],
+  prerequisites: [
+    {
+      name: "Ruby",
+      versionRange: RUBY_VERSION_RANGE,
+      preferredVersion: "3.2",
+      checkCommand: "ruby --version"
+    }
+  ],
+  /**
+   * Checks whether SQLint is available (Ruby runtime + sqlint gem).
+   *
+   * Checks:
+   * 1. Ruby runtime via findRuby
+   * 2. sqlint binary in the Codacy-managed gem directory or on PATH
+   */
+  async checkAvailability(ctx) {
+    ctx.logger.debug("Checking availability", { toolId: TOOL_ID });
+    const rubyInfo = await (0, import_tooling.findRuby)(RUBY_VERSION_RANGE, ctx.logger).catch(() => null);
+    let resolvedRubyPath = rubyInfo?.path;
+    const dependencies = rubyInfo ? [{ name: "Ruby", available: true, version: rubyInfo.version, installation: "global" }] : [{ name: "Ruby", available: false, reason: `Ruby (${RUBY_VERSION_RANGE}) not found` }];
+    if (!rubyInfo) {
+      const rubyBin = (0, import_tooling.resolvePortableRubyBinary)(ctx.globalDir, "3.2.11");
+      try {
+        await import_promises.default.access(rubyBin);
+        resolvedRubyPath = rubyBin;
+        dependencies[0] = {
+          name: "Ruby",
+          available: true,
+          version: "3.2.11",
+          installation: "codacy"
+        };
+      } catch {
+        return {
+          available: false,
+          reason: "Ruby runtime not found (required for SQLint)",
+          installHint: "Install Ruby 2.7+, or run with --install-dependencies for auto-download",
+          dependencies
+        };
+      }
+    }
+    const gemPaths = (0, import_tooling.getGemPaths)(ctx.globalDir, ADAPTER_ID);
+    const sqlintVersion = await (0, import_tooling.checkGemTool)(
+      gemPaths,
+      "sqlint",
+      "--version",
+      /(\d+\.\d+\.\d+)/,
+      resolvedRubyPath,
+      ctx.logger
+    );
+    if (sqlintVersion) {
+      return {
+        available: true,
+        version: sqlintVersion,
+        path: (0, import_tooling.resolveGemBinary)(gemPaths, "sqlint"),
+        installation: "codacy",
+        dependencies
+      };
+    }
+    try {
+      const { stdout, exitCode } = await (0, import_tooling.spawnTool)("sqlint", ["--version"], {
+        cwd: ctx.repositoryRoot,
+        logger: ctx.logger
+      });
+      if (exitCode === 0) {
+        const match = stdout.match(/(\d+\.\d+\.\d+)/);
+        if (match) {
+          return {
+            available: true,
+            version: match[1],
+            installation: "global",
+            dependencies
+          };
+        }
+      }
+    } catch {
+    }
+    return {
+      available: false,
+      reason: "SQLint not found in Codacy gem directory or on PATH",
+      installHint: "Run with --install-dependencies to auto-install, or run: gem install sqlint",
+      dependencies
+    };
+  },
+  /**
+   * Installs SQLint by ensuring a Ruby runtime is available and installing
+   * the sqlint gem into an isolated gem directory.
+   *
+   * Note: The sqlint gem depends on pg_query, which includes a native C
+   * extension. A C compiler is required on the system for installation.
+   */
+  async install(ctx) {
+    ctx.logger.info("Starting install", { toolId: TOOL_ID });
+    const ruby = await (0, import_tooling.ensureRuby)(ctx.globalDir, RUBY_VERSION_RANGE, ctx.logger);
+    if (!ruby) {
+      return {
+        success: false,
+        error: {
+          toolId: TOOL_ID,
+          phase: "requirementCheck",
+          kind: "MissingPrerequisite",
+          message: `Ruby (${RUBY_VERSION_RANGE}) could not be found or downloaded. SQLint requires a Ruby runtime.`,
+          level: "error"
+        }
+      };
+    }
+    try {
+      const gemPaths = (0, import_tooling.getGemPaths)(ctx.globalDir, ADAPTER_ID);
+      ctx.logger.info(`Installing SQLint ${SQLINT_VERSION} to ${gemPaths.gemHome}...`);
+      const prevConfigArgs = process.env.CONFIGURE_ARGS;
+      process.env.CONFIGURE_ARGS = `${prevConfigArgs ?? ""} --with-cflags=-DHAVE_STRCHRNUL`.trim();
+      try {
+        await (0, import_tooling.gemInstall)(gemPaths, ruby.path, ["google-protobuf:3.25.5"], ctx.logger);
+        await (0, import_tooling.gemInstall)(gemPaths, ruby.path, [`sqlint:${SQLINT_VERSION}`], ctx.logger);
+      } finally {
+        if (prevConfigArgs === void 0) {
+          delete process.env.CONFIGURE_ARGS;
+        } else {
+          process.env.CONFIGURE_ARGS = prevConfigArgs;
+        }
+      }
+      const installedPath = (0, import_tooling.resolveGemBinary)(gemPaths, "sqlint");
+      ctx.logger.info(`Installed SQLint to ${installedPath}`);
+      return { success: true, installedPath, installedVersion: SQLINT_VERSION };
+    } catch (err) {
+      return {
+        success: false,
+        error: {
+          toolId: TOOL_ID,
+          phase: "toolInstall",
+          kind: "InstallError",
+          message: `Failed to install SQLint: ${err instanceof Error ? err.message : String(err)}`,
+          level: "error"
+        }
+      };
+    }
+  },
+  /**
+   * SQLint has no configuration files -- it is a purely syntax-based checker.
+   * Always returns { found: false }.
+   */
+  async checkLocalConfigurationFile(_ctx) {
+    return { found: false };
+  },
+  /**
+   * Runs `sqlint` against the target SQL files and converts the text output
+   * into Codacy Issue objects.
+   *
+   * SQLint has no config generation and no rule selection -- it is a single
+   * umbrella pattern (`SQLint_allIssues`) that reports all syntax errors.
+   *
+   * Output format: one finding per line in the format:
+   *   file.sql:line:column:SEVERITY message
+   *
+   * Exit codes:
+   * - 0: no errors found
+   * - 1: errors found (normal -- not treated as an error)
+   *
+   * Never throws -- all errors are captured in the returned `errors` array.
+   */
+  async analyze(ctx, codacyConfig) {
+    const startMs = Date.now();
+    ctx.logger.info("Starting analysis", { toolId: TOOL_ID, fileCount: ctx.targetFiles.length });
+    const startedAt = /* @__PURE__ */ new Date();
+    const issues = [];
+    const errors = [];
+    if (ctx.targetFiles.length === 0) {
+      return buildResult(startedAt, /* @__PURE__ */ new Date(), issues, errors, 0);
+    }
+    const enabledPatterns = new Set(codacyConfig.patterns.map((p) => p.patternId));
+    if (!codacyConfig.useLocalConfigurationFile && codacyConfig.patterns.length === 0) {
+      ctx.logger.info("Skipping analysis: no patterns enabled", { toolId: TOOL_ID });
+      return buildResult(startedAt, /* @__PURE__ */ new Date(), issues, errors, ctx.targetFiles.length);
+    }
+    const invocation = await resolveToolInvocation(ctx);
+    const absoluteFiles = ctx.targetFiles.map((f) => import_path.default.resolve(ctx.repositoryRoot, f));
+    const args = [...invocation.prefixArgs, ...absoluteFiles];
+    try {
+      const gemPaths = (0, import_tooling.getGemPaths)(ctx.globalDir, ADAPTER_ID);
+      const env = (0, import_tooling.buildGemEnv)(gemPaths, invocation.rubyPath);
+      const { stdout, stderr, exitCode } = await (0, import_tooling.spawnTool)(invocation.binary, args, {
+        cwd: ctx.repositoryRoot,
+        env,
+        logger: ctx.logger
+      });
+      if (exitCode !== 0 && exitCode !== 1) {
+        errors.push({
+          toolId: TOOL_ID,
+          phase: "toolInvoke",
+          kind: "NonZeroExit",
+          message: `sqlint exited with code ${exitCode}${stderr ? `: ${stderr.trim()}` : ""}`,
+          level: "error"
+        });
+        return buildResult(startedAt, /* @__PURE__ */ new Date(), issues, errors, ctx.targetFiles.length);
+      }
+      const output = stdout + (stderr || "");
+      const outputLines = output.split("\n").filter((l) => l.trim());
+      const fileLineCache = /* @__PURE__ */ new Map();
+      const meta = ruleMetadata();
+      for (const outputLine of outputLines) {
+        const match = OUTPUT_LINE_REGEX.exec(outputLine);
+        if (!match) continue;
+        const [, rawFilePath, lineStr, colStr, , message] = match;
+        const line = parseInt(lineStr, 10);
+        const column = parseInt(colStr, 10);
+        let filePath = rawFilePath;
+        if (import_path.default.isAbsolute(filePath)) {
+          filePath = import_path.default.relative(ctx.repositoryRoot, filePath);
+        }
+        if (enabledPatterns.size > 0 && !enabledPatterns.has(UMBRELLA_PATTERN)) {
+          continue;
+        }
+        const absPath = import_path.default.resolve(ctx.repositoryRoot, filePath);
+        if (!fileLineCache.has(absPath)) {
+          fileLineCache.set(absPath, await readFileLines(absPath));
+        }
+        const fileLines = fileLineCache.get(absPath);
+        issues.push({
+          filePath,
+          patternId: UMBRELLA_PATTERN,
+          toolId: TOOL_ID,
+          line,
+          column,
+          message,
+          lineContent: getLineContent(fileLines, line),
+          multilineContent: (0, import_tooling.getMultilineContent)(fileLines, line, void 0),
+          category: meta.category,
+          severity: meta.severity
+        });
+      }
+    } catch (invokeErr) {
+      errors.push({
+        toolId: TOOL_ID,
+        phase: "toolInvoke",
+        kind: "InvocationError",
+        message: `Failed to run SQLint: ${invokeErr instanceof Error ? invokeErr.message : String(invokeErr)}`,
+        level: "error"
+      });
+    }
+    const durationMs = Date.now() - startMs;
+    ctx.logger.info("Analysis complete", {
+      toolId: TOOL_ID,
+      issueCount: issues.length,
+      errorCount: errors.length,
+      durationMs
+    });
+    return buildResult(startedAt, /* @__PURE__ */ new Date(), issues, errors, ctx.targetFiles.length);
+  }
+};
+
+// src/index.ts
+var index_default = (0, import_tooling2.defineToolAdapter)(adapter);

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@codacy/tools-sqlint-0",
+  "version": "0.3.0",
+  "description": "SQLint adapter — CLI-mode SQL syntax checker",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@codacy/tooling": "0.3.0"
+  },
+  "license": "MIT",
+  "author": "Codacy <support@codacy.com> (https://www.codacy.com)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codacy/analysis-cli.git",
+    "directory": "packages/tools/sqlint-0"
+  },
+  "homepage": "https://github.com/codacy/analysis-cli",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs --dts --clean",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "clean": "rm -rf dist",
+    "prefetch": "node ../scripts/fetch-patterns.mjs 25b6766b-06c6-4625-9df1-561d28386b5f src/patterns.json"
+  }
+}