feat: Jinja/dbt template preprocessing for SQL analysis tools

packages/altimate-code/src/bridge/engine.ts

@@ -179,7 +179,7 @@ async function ensureEngineImpl(): Promise<void> {
         timestamp: Date.now(),
         session_id: Telemetry.getContext().sessionId,
         phase: "venv_create",
-        error_message: (e?.stderr?.toString() || e?.message ?? String(e)).slice(0, 500),
+        error_message: ((e?.stderr?.toString() || e?.message) ?? String(e)).slice(0, 500),
       })
       throw e
     }
@@ -196,7 +196,7 @@ async function ensureEngineImpl(): Promise<void> {
       timestamp: Date.now(),
       session_id: Telemetry.getContext().sessionId,
       phase: "pip_install",
-      error_message: (e?.stderr?.toString() || e?.message ?? String(e)).slice(0, 500),
+      error_message: ((e?.stderr?.toString() || e?.message) ?? String(e)).slice(0, 500),
     })
     throw e
   }

packages/altimate-code/src/bridge/protocol.ts

@@ -951,6 +951,25 @@ export interface LocalTestResult {
   error?: string
 }
 
+// --- Jinja Preprocessing ---
+
+export interface SqlPreprocessJinjaParams {
+  sql: string
+}
+
+export interface SqlPreprocessJinjaResult {
+  success: boolean
+  preprocessed_sql: string
+  original_sql: string
+  was_preprocessed: boolean
+  refs_found: string[]
+  sources_found: string[]
+  variables_found: string[]
+  macros_removed: string[]
+  warnings: string[]
+  error?: string
+}
+
 // --- Method registry ---
 
 export const BridgeMethods = {
@@ -986,6 +1005,7 @@ export const BridgeMethods = {
   "schema.detect_pii": {} as { params: PiiDetectParams; result: PiiDetectResult },
   "schema.tags": {} as { params: TagsGetParams; result: TagsGetResult },
   "schema.tags_list": {} as { params: TagsListParams; result: TagsListResult },
+  "sql.preprocess_jinja": {} as { params: SqlPreprocessJinjaParams; result: SqlPreprocessJinjaResult },
   "sql.diff": {} as { params: SqlDiffParams; result: SqlDiffResult },
   "sql.rewrite": {} as { params: SqlRewriteParams; result: SqlRewriteResult },
   "sql.schema_diff": {} as { params: SchemaDiffParams; result: SchemaDiffResult },

packages/altimate-code/src/tool/registry.ts

@@ -56,6 +56,7 @@ import { FinopsRoleGrantsTool, FinopsRoleHierarchyTool, FinopsUserRolesTool } fr
 import { SchemaDetectPiiTool } from "./schema-detect-pii"
 import { SchemaTagsTool, SchemaTagsListTool } from "./schema-tags"
 import { SqlRewriteTool } from "./sql-rewrite"
+import { SqlPreprocessJinjaTool } from "./sql-preprocess-jinja"
 
 import { SchemaDiffTool } from "./schema-diff"
 import { AltimateCoreValidateTool } from "./altimate-core-validate"
@@ -219,6 +220,7 @@ export namespace ToolRegistry {
       SchemaTagsTool,
       SchemaTagsListTool,
       SqlRewriteTool,
+      SqlPreprocessJinjaTool,
       SchemaDiffTool,
       AltimateCoreValidateTool,
       AltimateCoreLintTool,

packages/altimate-code/src/tool/sql-preprocess-jinja.ts

@@ -0,0 +1,103 @@
+import z from "zod"
+import { Tool } from "./tool"
+import { Bridge } from "../bridge/client"
+import type { SqlPreprocessJinjaResult } from "../bridge/protocol"
+
+export const SqlPreprocessJinjaTool = Tool.define("sql_preprocess_jinja", {
+  description:
+    "Preprocess Jinja/dbt template syntax in SQL before analysis. Stubs common dbt macros like {{ ref() }}, {{ source() }}, {{ config() }}, {{ var() }}, {{ this }}, and Jinja block tags ({% if %}, {% for %}) into plain SQL that downstream tools can parse. Use this when SQL analysis tools fail on dbt-templated SQL.",
+  parameters: z.object({
+    sql: z.string().describe("SQL with Jinja/dbt template syntax to preprocess"),
+  }),
+  async execute(args, ctx) {
+    try {
+      const result = await Bridge.call("sql.preprocess_jinja", {
+        sql: args.sql,
+      })
+
+      if (!result.was_preprocessed) {
+        return {
+          title: "Preprocess Jinja: no templates found",
+          metadata: {
+            success: true as boolean,
+            was_preprocessed: false as boolean,
+            refs: [] as string[],
+            sources: [] as string[],
+            variables: [] as string[],
+          },
+          output: "No Jinja templates detected in the SQL. The input is already plain SQL.",
+        }
+      }
+
+      return {
+        title: `Preprocess Jinja: ${formatSummary(result)}`,
+        metadata: {
+          success: result.success,
+          was_preprocessed: result.was_preprocessed,
+          refs: result.refs_found,
+          sources: result.sources_found,
+          variables: result.variables_found,
+        },
+        output: formatResult(result),
+      }
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      return {
+        title: "Preprocess Jinja: ERROR",
+        metadata: {
+          success: false as boolean,
+          was_preprocessed: false as boolean,
+          refs: [] as string[],
+          sources: [] as string[],
+          variables: [] as string[],
+        },
+        output: `Failed to preprocess Jinja: ${msg}\n\nEnsure the Python bridge is running and altimate-engine is installed.`,
+      }
+    }
+  },
+})
+
+function formatSummary(result: SqlPreprocessJinjaResult): string {
+  const parts: string[] = []
+  if (result.refs_found.length > 0) parts.push(`${result.refs_found.length} ref(s)`)
+  if (result.sources_found.length > 0) parts.push(`${result.sources_found.length} source(s)`)
+  if (result.variables_found.length > 0) parts.push(`${result.variables_found.length} var(s)`)
+  return parts.length > 0 ? parts.join(", ") : "templates removed"
+}
+
+function formatResult(result: SqlPreprocessJinjaResult): string {
+  const lines: string[] = []
+
+  lines.push("=== Preprocessed SQL ===")
+  lines.push(result.preprocessed_sql)
+  lines.push("")
+
+  if (result.refs_found.length > 0) {
+    lines.push(`Models referenced (ref): ${result.refs_found.join(", ")}`)
+  }
+  if (result.sources_found.length > 0) {
+    lines.push(`Sources referenced: ${result.sources_found.join(", ")}`)
+  }
+  if (result.variables_found.length > 0) {
+    lines.push(`Variables used (var): ${result.variables_found.join(", ")}`)
+  }
+  if (result.macros_removed.length > 0) {
+    lines.push(`Macros removed: ${result.macros_removed.join(", ")}`)
+  }
+
+  if (result.warnings.length > 0) {
+    lines.push("")
+    lines.push("=== Warnings ===")
+    for (const w of result.warnings) {
+      lines.push(`  ! ${w}`)
+    }
+  }
+
+  lines.push("")
+  lines.push(
+    "Note: Jinja templates were stubbed with placeholder values. " +
+      "Analysis results on this SQL are approximate.",
+  )
+
+  return lines.join("\n")
+}

packages/altimate-engine/src/altimate_engine/models.py

@@ -987,6 +987,26 @@ class AltimateCoreIsSafeParams(BaseModel):
     sql: str
 
 
+# --- Jinja Preprocessing ---
+
+
+class SqlPreprocessJinjaParams(BaseModel):
+    sql: str
+
+
+class SqlPreprocessJinjaResult(BaseModel):
+    success: bool = True
+    preprocessed_sql: str
+    original_sql: str
+    was_preprocessed: bool
+    refs_found: list[str] = Field(default_factory=list)
+    sources_found: list[str] = Field(default_factory=list)
+    variables_found: list[str] = Field(default_factory=list)
+    macros_removed: list[str] = Field(default_factory=list)
+    warnings: list[str] = Field(default_factory=list)
+    error: str | None = None
+
+
 # --- JSON-RPC ---