codeql-development-mcp-server 2.25.1-next.1 → 2.25.1-next.2

package/dist/codeql-development-mcp-server.js

@@ -30698,7 +30698,8 @@ var require_dist2 = __commonJS({
     }
     function pathToRegexp(path3, options = {}) {
       const { delimiter: delimiter7 = DEFAULT_DELIMITER, end = true, sensitive = false, trailing = true } = options;
-      const root = new SourceNode("^");
+      const keys = [];
+      const sources = [];
       const paths = [path3];
       let combinations = 0;
       while (paths.length) {
@@ -30712,39 +30713,15 @@ var require_dist2 = __commonJS({
           if (combinations++ >= 256) {
             throw new PathError("Too many path combinations", data.originalPath);
           }
-          let node = root;
-          for (const part of toRegExpSource(tokens, delimiter7, data.originalPath)) {
-            node = node.add(part.source, part.key);
-          }
-          node.add("");
+          sources.push(toRegExpSource(tokens, delimiter7, keys, data.originalPath));
         });
       }
-      const keys = [];
-      let pattern = toRegExp(root, keys);
+      let pattern = `^(?:${sources.join("|")})`;
       if (trailing)
         pattern += "(?:" + escape2(delimiter7) + "$)?";
       pattern += end ? "$" : "(?=" + escape2(delimiter7) + "|$)";
       return { regexp: new RegExp(pattern, sensitive ? "" : "i"), keys };
     }
-    function toRegExp(node, keys) {
-      if (node.key)
-        keys.push(node.key);
-      const children = Object.keys(node.children);
-      const text = children.map((id) => toRegExp(node.children[id], keys)).join("|");
-      return node.source + (children.length < 2 ? text : `(?:${text})`);
-    }
-    var SourceNode = class _SourceNode {
-      constructor(source, key) {
-        this.source = source;
-        this.key = key;
-        this.children = /* @__PURE__ */ Object.create(null);
-      }
-      add(source, key) {
-        var _a;
-        const id = source + ":" + (key ? key.name : "");
-        return (_a = this.children)[id] || (_a[id] = new _SourceNode(source, key));
-      }
-    };
     function flatten(tokens, index, result, callback) {
       while (index < tokens.length) {
         const token = tokens[index++];
@@ -30756,8 +30733,8 @@ var require_dist2 = __commonJS({
       }
       callback(result);
     }
-    function toRegExpSource(tokens, delimiter7, originalPath) {
-      let result = [];
+    function toRegExpSource(tokens, delimiter7, keys, originalPath) {
+      let result = "";
       let backtrack = "";
       let wildcardBacktrack = "";
       let prevCaptureType = 0;
@@ -30788,7 +30765,7 @@ var require_dist2 = __commonJS({
       while (index < tokens.length) {
         const token = tokens[index++];
         if (token.type === "text") {
-          result.push({ source: escape2(token.value) });
+          result += escape2(token.value);
           backtrack += token.value;
           if (prevCaptureType === 2)
             wildcardBacktrack += token.value;
@@ -30801,19 +30778,14 @@ var require_dist2 = __commonJS({
             throw new PathError(`Missing text before "${token.name}" ${token.type}`, originalPath);
           }
           if (token.type === "param") {
-            result.push({
-              source: hasSegmentCapture ? `(${negate(delimiter7, backtrack)}+?)` : hasInSegment(index, "wildcard") ? `(${negate(delimiter7, peekText(index))}+?)` : `(${negate(delimiter7, "")}+?)`,
-              key: token
-            });
+            result += hasSegmentCapture & 2 ? `(${negate(delimiter7, backtrack)}+)` : hasInSegment(index, "wildcard") ? `(${negate(delimiter7, peekText(index))}+)` : hasSegmentCapture & 1 ? `(${negate(delimiter7, backtrack)}+|${escape2(backtrack)})` : `(${negate(delimiter7, "")}+)`;
             hasSegmentCapture |= prevCaptureType = 1;
           } else {
-            result.push({
-              source: hasSegmentCapture & 2 ? `(${negate(backtrack, "")}+?)` : hasSegmentCapture & 1 ? `(${negate(wildcardBacktrack, "")}+?)` : wildcardBacktrack ? `(${negate(wildcardBacktrack, "")}+?|${negate(delimiter7, "")}+?)` : `([^]+?)`,
-              key: token
-            });
+            result += hasSegmentCapture & 2 ? `(${negate(backtrack, "")}+)` : wildcardBacktrack ? `(${negate(wildcardBacktrack, "")}+|${negate(delimiter7, "")}+)` : `([^]+)`;
             wildcardBacktrack = "";
             hasSegmentCapture |= prevCaptureType = 2;
           }
+          keys.push(token);
           backtrack = "";
           continue;
         }
@@ -165001,7 +164973,11 @@ var require_utils5 = __commonJS({
           try {
             stat = self2.fs.statSync(resolvedPath);
           } catch (e) {
-            self2.fs.mkdirSync(resolvedPath);
+            if (e.message && e.message.startsWith("ENOENT")) {
+              self2.fs.mkdirSync(resolvedPath);
+            } else {
+              throw e;
+            }
           }
           if (stat && stat.isFile()) throw Errors.FILE_IN_THE_WAY(`"${resolvedPath}"`);
         });
@@ -165198,9 +165174,9 @@ var require_utils5 = __commonJS({
       }
     };
     Utils.readBigUInt64LE = function(buffer, index) {
-      var slice = Buffer.from(buffer.slice(index, index + 8));
-      slice.swap64();
-      return parseInt(`0x${slice.toString("hex")}`);
+      const lo = buffer.readUInt32LE(index);
+      const hi = buffer.readUInt32LE(index + 4);
+      return hi * 4294967296 + lo;
     };
     Utils.fromDOS2Date = function(val) {
       return new Date((val >> 25 & 127) + 1980, Math.max((val >> 21 & 15) - 1, 0), Math.max(val >> 16 & 31, 1), val >> 11 & 31, val >> 5 & 63, (val & 31) << 1);
@@ -165382,6 +165358,7 @@ var require_entryHeader = __commonJS({
           return Utils.fromDOS2Date(this.timeval);
         },
         set time(val) {
+          val = new Date(val);
           this.timeval = Utils.fromDate2DOS(val);
         },
         get timeval() {
@@ -165482,6 +165459,7 @@ var require_entryHeader = __commonJS({
           }
           _localHeader.version = data.readUInt16LE(Constants.LOCVER);
           _localHeader.flags = data.readUInt16LE(Constants.LOCFLG);
+          _localHeader.flags_desc = (_localHeader.flags & Constants.FLG_DESC) > 0;
           _localHeader.method = data.readUInt16LE(Constants.LOCHOW);
           _localHeader.time = data.readUInt32LE(Constants.LOCTIM);
           _localHeader.crc = data.readUInt32LE(Constants.LOCCRC);
@@ -165891,7 +165869,7 @@ var require_zipEntry = __commonJS({
         return input.slice(_centralHeader.realDataOffset, _centralHeader.realDataOffset + _centralHeader.compressedSize);
       }
       function crc32OK(data) {
-        if (!_centralHeader.flags_desc) {
+        if (!_centralHeader.flags_desc && !_centralHeader.localHeader.flags_desc) {
           if (Utils.crc32(data) !== _centralHeader.localHeader.crc) {
             return false;
           }
@@ -166020,7 +165998,7 @@ var require_zipEntry = __commonJS({
         }
       }
       function readUInt64LE(buffer, offset) {
-        return (buffer.readUInt32LE(offset + 4) << 4) + buffer.readUInt32LE(offset);
+        return Utils.readBigUInt64LE(buffer, offset);
       }
       function parseExtra(data) {
         try {
@@ -166612,7 +166590,7 @@ var require_adm_zip = __commonJS({
       }
       function fixPath(zipPath) {
         const { join: join22, normalize: normalize2, sep: sep3 } = pth.posix;
-        return join22(".", normalize2(sep3 + zipPath.split("\\").join(sep3) + sep3));
+        return join22(pth.isAbsolute(zipPath) ? "/" : ".", normalize2(sep3 + zipPath.split("\\").join(sep3) + sep3));
       }
       function filenameFilter(filterfn) {
         if (filterfn instanceof RegExp) {
@@ -176078,10 +176056,9 @@ var ProgressTokenSchema = union([string2(), number2().int()]);
 var CursorSchema = string2();
 var TaskCreationParamsSchema = looseObject({
   /**
-   * Time in milliseconds to keep task results available after completion.
-   * If null, the task has unlimited lifetime until manually cleaned up.
+   * Requested duration in milliseconds to retain task from creation.
    */
-  ttl: union([number2(), _null3()]).optional(),
+  ttl: number2().optional(),
   /**
    * Time in milliseconds to wait between task status requests.
    */
@@ -176381,7 +176358,11 @@ var ClientCapabilitiesSchema = object2({
   /**
    * Present if the client supports task creation.
    */
-  tasks: ClientTasksCapabilitySchema.optional()
+  tasks: ClientTasksCapabilitySchema.optional(),
+  /**
+   * Extensions that the client supports. Keys are extension identifiers (vendor-prefix/extension-name).
+   */
+  extensions: record(string2(), AssertObjectSchema).optional()
 });
 var InitializeRequestParamsSchema = BaseRequestParamsSchema.extend({
   /**
@@ -176443,7 +176424,11 @@ var ServerCapabilitiesSchema = object2({
   /**
    * Present if the server supports task creation.
    */
-  tasks: ServerTasksCapabilitySchema.optional()
+  tasks: ServerTasksCapabilitySchema.optional(),
+  /**
+   * Extensions that the server supports. Keys are extension identifiers (vendor-prefix/extension-name).
+   */
+  extensions: record(string2(), AssertObjectSchema).optional()
 });
 var InitializeResultSchema = ResultSchema.extend({
   /**
@@ -176635,6 +176620,12 @@ var ResourceSchema = object2({
    * The MIME type of this resource, if known.
    */
   mimeType: optional(string2()),
+  /**
+   * The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.
+   *
+   * This can be used by Hosts to display file sizes and estimate context window usage.
+   */
+  size: optional(number2()),
   /**
    * Optional annotations for the client.
    */
@@ -181540,7 +181531,7 @@ var StdioServerTransport = class {
 };
 
 // ../node_modules/@hono/node-server/dist/index.mjs
-import { Http2ServerRequest as Http2ServerRequest2 } from "http2";
+import { Http2ServerRequest as Http2ServerRequest2, constants as h2constants } from "http2";
 import { Http2ServerRequest } from "http2";
 import { Readable } from "stream";
 import crypto2 from "crypto";
@@ -181863,6 +181854,50 @@ if (typeof global.crypto === "undefined") {
   global.crypto = crypto2;
 }
 var outgoingEnded = /* @__PURE__ */ Symbol("outgoingEnded");
+var incomingDraining = /* @__PURE__ */ Symbol("incomingDraining");
+var DRAIN_TIMEOUT_MS = 500;
+var MAX_DRAIN_BYTES = 64 * 1024 * 1024;
+var drainIncoming = (incoming) => {
+  const incomingWithDrainState = incoming;
+  if (incoming.destroyed || incomingWithDrainState[incomingDraining]) {
+    return;
+  }
+  incomingWithDrainState[incomingDraining] = true;
+  if (incoming instanceof Http2ServerRequest2) {
+    try {
+      ;
+      incoming.stream?.close?.(h2constants.NGHTTP2_NO_ERROR);
+    } catch {
+    }
+    return;
+  }
+  let bytesRead = 0;
+  const cleanup = () => {
+    clearTimeout(timer);
+    incoming.off("data", onData);
+    incoming.off("end", cleanup);
+    incoming.off("error", cleanup);
+  };
+  const forceClose = () => {
+    cleanup();
+    const socket = incoming.socket;
+    if (socket && !socket.destroyed) {
+      socket.destroySoon();
+    }
+  };
+  const timer = setTimeout(forceClose, DRAIN_TIMEOUT_MS);
+  timer.unref?.();
+  const onData = (chunk) => {
+    bytesRead += chunk.length;
+    if (bytesRead > MAX_DRAIN_BYTES) {
+      forceClose();
+    }
+  };
+  incoming.on("data", onData);
+  incoming.on("end", cleanup);
+  incoming.on("error", cleanup);
+  incoming.resume();
+};
 var handleRequestError = () => new Response(null, {
   status: 400
 });
@@ -182034,14 +182069,18 @@ var getRequestListener = (fetchCallback, options = {}) => {
               setTimeout(() => {
                 if (!incomingEnded) {
                   setTimeout(() => {
-                    incoming.destroy();
-                    outgoing.destroy();
+                    drainIncoming(incoming);
                   });
                 }
               });
             }
           };
         }
+        outgoing.on("finish", () => {
+          if (!incomingEnded) {
+            drainIncoming(incoming);
+          }
+        });
       }
       outgoing.on("close", () => {
         const abortController = req[abortControllerKey];
@@ -182056,7 +182095,7 @@ var getRequestListener = (fetchCallback, options = {}) => {
           setTimeout(() => {
             if (!incomingEnded) {
               setTimeout(() => {
-                incoming.destroy();
+                drainIncoming(incoming);
               });
             }
           });
@@ -182798,7 +182837,7 @@ var StreamableHTTPServerTransport = class {
 var import_express = __toESM(require_express2(), 1);
 var import_cors = __toESM(require_lib4(), 1);
 var import_dotenv = __toESM(require_main(), 1);
-import { realpathSync as realpathSync2 } from "fs";
+import { realpathSync as realpathSync3 } from "fs";
 import { resolve as resolve14 } from "path";
 import { pathToFileURL as pathToFileURL5 } from "url";
 
@@ -182808,7 +182847,7 @@ init_cli_executor();
 // src/lib/database-resolver.ts
 init_logger();
 import { basename as basename2, join as join6 } from "path";
-import { existsSync as existsSync4, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { existsSync as existsSync4, readdirSync as readdirSync2, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
 var databasePathCache = /* @__PURE__ */ new Map();
 function resolveDatabasePath(dbPath) {
   const cached2 = databasePathCache.get(dbPath);
@@ -182848,6 +182887,41 @@ function resolveDatabasePath(dbPath) {
   databasePathCache.set(dbPath, dbPath);
   return dbPath;
 }
+function readDatabaseMetadata(databasePath) {
+  for (const filename of ["codeql-database.yml", "codeql-database.yaml"]) {
+    try {
+      const content = readFileSync4(join6(databasePath, filename), "utf8");
+      return parseDatabaseYmlContent(content);
+    } catch {
+    }
+  }
+  return {};
+}
+function parseDatabaseYmlContent(content) {
+  const metadata = {};
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    const colonIdx = trimmed.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = trimmed.substring(0, colonIdx).trim();
+    const value = trimmed.substring(colonIdx + 1).trim().replace(/^["']|["']$/g, "");
+    switch (key) {
+      case "primaryLanguage":
+        metadata.language = value;
+        break;
+      case "sourceLocationPrefix":
+        metadata.sourceLocationPrefix = value;
+        break;
+      case "cliVersion":
+        metadata.cliVersion = value;
+        break;
+      case "creationTime":
+        metadata.creationTime = value;
+        break;
+    }
+  }
+  return metadata;
+}
 
 // src/lib/cli-tool-registry.ts
 init_logger();
@@ -182940,13 +183014,13 @@ async function resolveQueryPath(params, logger2) {
 // src/lib/result-processor.ts
 init_cli_executor();
 import { basename as basename4, dirname as dirname4 } from "path";
-import { mkdirSync as mkdirSync7, readFileSync as readFileSync6 } from "fs";
+import { mkdirSync as mkdirSync7, readFileSync as readFileSync7 } from "fs";
 import { createHash as createHash2 } from "crypto";
 
 // src/lib/query-results-evaluator.ts
 init_cli_executor();
 init_logger();
-import { closeSync, fstatSync, mkdirSync as mkdirSync4, openSync, readFileSync as readFileSync4, writeFileSync } from "fs";
+import { closeSync, fstatSync, mkdirSync as mkdirSync4, openSync, readFileSync as readFileSync5, writeFileSync } from "fs";
 import { dirname as dirname3, isAbsolute as isAbsolute3 } from "path";
 var BUILT_IN_EVALUATORS = {
   "json-decode": "JSON format decoder for query results",
@@ -182968,7 +183042,7 @@ async function extractQueryMetadata(queryPath) {
         metadataCache.set(queryPath, cached2);
         return cached2.metadata;
       }
-      queryContent = readFileSync4(fd, "utf-8");
+      queryContent = readFileSync5(fd, "utf-8");
     } finally {
       closeSync(fd);
     }
@@ -183223,6 +183297,444 @@ async function evaluateWithCustomScript(_bqrsPath, _queryPath, _scriptPath, _out
   };
 }
 
+// src/lib/sarif-utils.ts
+function getRuleDisplayName(rule) {
+  return rule.shortDescription?.text ?? rule.name ?? rule.id;
+}
+function collectAllRules(run) {
+  const driverRules = run.tool.driver.rules ?? [];
+  const extensionRules = [];
+  for (const ext of run.tool.extensions ?? []) {
+    if (ext.rules) {
+      extensionRules.push(...ext.rules);
+    }
+  }
+  return [...driverRules, ...extensionRules];
+}
+function extractPrimaryLocations(result) {
+  return (result.locations ?? []).filter((loc) => loc.physicalLocation?.artifactLocation?.uri).map((loc) => ({
+    endColumn: loc.physicalLocation.region?.endColumn,
+    endLine: loc.physicalLocation.region?.endLine ?? loc.physicalLocation.region?.startLine,
+    startColumn: loc.physicalLocation.region?.startColumn,
+    startLine: loc.physicalLocation.region?.startLine,
+    uri: loc.physicalLocation.artifactLocation.uri
+  }));
+}
+function extractSourceLocations(result) {
+  const flows = result.codeFlows ?? [];
+  const sources = [];
+  for (const flow of flows) {
+    for (const tf of flow.threadFlows ?? []) {
+      const steps = tf.locations ?? [];
+      if (steps.length > 0) {
+        const firstStep = steps[0];
+        const loc = firstStep.location?.physicalLocation;
+        if (loc?.artifactLocation?.uri) {
+          sources.push({
+            endColumn: loc.region?.endColumn,
+            endLine: loc.region?.endLine ?? loc.region?.startLine,
+            startColumn: loc.region?.startColumn,
+            startLine: loc.region?.startLine,
+            uri: loc.artifactLocation.uri
+          });
+        }
+      }
+    }
+  }
+  return sources;
+}
+function extractAllLocations(result) {
+  const locs = [...extractPrimaryLocations(result)];
+  for (const rl of result.relatedLocations ?? []) {
+    if (rl.physicalLocation?.artifactLocation?.uri) {
+      locs.push({
+        endColumn: rl.physicalLocation.region?.endColumn,
+        endLine: rl.physicalLocation.region?.endLine ?? rl.physicalLocation.region?.startLine,
+        startColumn: rl.physicalLocation.region?.startColumn,
+        startLine: rl.physicalLocation.region?.startLine,
+        uri: rl.physicalLocation.artifactLocation.uri
+      });
+    }
+  }
+  for (const flow of result.codeFlows ?? []) {
+    for (const tf of flow.threadFlows ?? []) {
+      for (const step of tf.locations ?? []) {
+        const loc = step.location?.physicalLocation;
+        if (loc?.artifactLocation?.uri) {
+          locs.push({
+            endColumn: loc.region?.endColumn,
+            endLine: loc.region?.endLine ?? loc.region?.startLine,
+            startColumn: loc.region?.startColumn,
+            startLine: loc.region?.startLine,
+            uri: loc.artifactLocation.uri
+          });
+        }
+      }
+    }
+  }
+  return locs;
+}
+function extractFullPathLocations(result) {
+  const flows = result.codeFlows ?? [];
+  const locs = [];
+  for (const flow of flows) {
+    for (const tf of flow.threadFlows ?? []) {
+      for (const step of tf.locations ?? []) {
+        const loc = step.location?.physicalLocation;
+        if (loc?.artifactLocation?.uri) {
+          locs.push({
+            endColumn: loc.region?.endColumn,
+            endLine: loc.region?.endLine ?? loc.region?.startLine,
+            startColumn: loc.region?.startColumn,
+            startLine: loc.region?.startLine,
+            uri: loc.artifactLocation.uri
+          });
+        }
+      }
+    }
+  }
+  return locs;
+}
+function normalizeUri(uri) {
+  let normalized = uri;
+  if (normalized.startsWith("file:///")) {
+    normalized = normalized.substring(7);
+  } else if (normalized.startsWith("file://")) {
+    normalized = normalized.substring(5);
+  }
+  try {
+    normalized = decodeURIComponent(normalized);
+  } catch {
+  }
+  normalized = normalized.replace(/\\/g, "/");
+  normalized = normalized.replace(/^\/+/, "");
+  return normalized;
+}
+function urisMatch(uriA, uriB) {
+  const a = normalizeUri(uriA);
+  const b = normalizeUri(uriB);
+  if (a === b) return true;
+  return a.endsWith(b) || b.endsWith(a);
+}
+function regionsOverlap(a, b) {
+  if (!urisMatch(a.uri, b.uri)) return false;
+  const aStartLine = a.startLine ?? 0;
+  const aEndLine = a.endLine ?? aStartLine;
+  const bStartLine = b.startLine ?? 0;
+  const bEndLine = b.endLine ?? bStartLine;
+  if (aEndLine < bStartLine || bEndLine < aStartLine) return false;
+  if (aStartLine === aEndLine && bStartLine === bEndLine && aStartLine === bStartLine) {
+    const aStartCol = a.startColumn ?? 0;
+    const aEndCol = a.endColumn ?? Infinity;
+    const bStartCol = b.startColumn ?? 0;
+    const bEndCol = b.endColumn ?? Infinity;
+    if (aEndCol < bStartCol || bEndCol < aStartCol) return false;
+  }
+  return true;
+}
+function locationKey(loc) {
+  return `${normalizeUri(loc.uri)}:${loc.startLine ?? "?"}:${loc.startColumn ?? "?"}`;
+}
+function findSharedLocations(locsA, locsB) {
+  const shared = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const a of locsA) {
+    for (const b of locsB) {
+      if (regionsOverlap(a, b)) {
+        const key = `${locationKey(a)}|${locationKey(b)}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          shared.push({
+            endColumn: a.endColumn,
+            endLine: a.endLine,
+            startColumn: a.startColumn,
+            startLine: a.startLine,
+            uri: a.uri
+          });
+        }
+      }
+    }
+  }
+  return shared;
+}
+function extractRuleFromSarif(sarif, ruleId) {
+  const run = sarif.runs[0];
+  if (!run) {
+    return { ...sarif, runs: [{ tool: { driver: { name: "CodeQL", rules: [] } }, results: [] }] };
+  }
+  const allRules = collectAllRules(run);
+  const matchingRules = allRules.filter((r) => r.id === ruleId);
+  const matchingResults = (run.results ?? []).filter((r) => r.ruleId === ruleId).map((r) => ({ ...r, ruleIndex: 0 }));
+  const extractedRun = {
+    tool: {
+      driver: {
+        ...run.tool.driver,
+        rules: matchingRules
+      },
+      extensions: run.tool.extensions
+    },
+    results: matchingResults
+  };
+  if (run.properties) {
+    extractedRun.properties = run.properties;
+  }
+  return {
+    version: sarif.version,
+    $schema: sarif.$schema,
+    runs: [extractedRun]
+  };
+}
+function decomposeSarifByRule(sarif) {
+  const run = sarif.runs[0];
+  if (!run) return /* @__PURE__ */ new Map();
+  const results = run.results ?? [];
+  const ruleIds = new Set(results.map((r) => r.ruleId));
+  const map2 = /* @__PURE__ */ new Map();
+  for (const ruleId of ruleIds) {
+    map2.set(ruleId, extractRuleFromSarif(sarif, ruleId));
+  }
+  return map2;
+}
+function sanitizeMermaidLabel(text) {
+  let sanitized = text.replace(/"/g, "#quot;");
+  if (sanitized.length > 60) {
+    sanitized = sanitized.substring(0, 57) + "...";
+  }
+  return sanitized;
+}
+function sarifResultToMermaid(result, _rule) {
+  const flows = result.codeFlows;
+  if (!flows || flows.length === 0) return "";
+  const threadFlow = flows[0]?.threadFlows?.[0];
+  if (!threadFlow || !threadFlow.locations || threadFlow.locations.length === 0) return "";
+  const steps = threadFlow.locations;
+  const lines = ["flowchart LR"];
+  const nodeIds = [];
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const loc = step.location?.physicalLocation;
+    const message = step.location?.message?.text ?? "(step)";
+    const uri = loc?.artifactLocation?.uri ?? "unknown";
+    const line = loc?.region?.startLine ?? "?";
+    const fileName = uri.split("/").pop() ?? uri;
+    const nodeId = String.fromCharCode(65 + i % 26) + (i >= 26 ? String(Math.floor(i / 26)) : "");
+    nodeIds.push(nodeId);
+    const label = sanitizeMermaidLabel(message);
+    lines.push(`    ${nodeId}["${label}<br/>${fileName}:${line}"]`);
+  }
+  for (let i = 0; i < nodeIds.length - 1; i++) {
+    lines.push(`    ${nodeIds[i]} --> ${nodeIds[i + 1]}`);
+  }
+  if (nodeIds.length >= 2) {
+    lines.push(`    style ${nodeIds[0]} fill:#d4edda`);
+    lines.push(`    style ${nodeIds[nodeIds.length - 1]} fill:#f8d7da`);
+  }
+  return lines.join("\n");
+}
+function sarifRuleToMarkdown(sarif, ruleId) {
+  const extracted = extractRuleFromSarif(sarif, ruleId);
+  const run = extracted.runs[0];
+  const results = run.results ?? [];
+  const rules = run.tool.driver.rules ?? [];
+  if (results.length === 0 && rules.length === 0) return "";
+  const rule = rules[0];
+  const lines = [];
+  lines.push(`## ${ruleId}`);
+  lines.push("");
+  if (rule) {
+    const name = getRuleDisplayName(rule);
+    lines.push(`**Name**: ${name}`);
+    const props = rule.properties;
+    if (props) {
+      const parts = [];
+      if (props.kind) parts.push(`**Kind**: ${props.kind}`);
+      if (props.precision) parts.push(`**Precision**: ${props.precision}`);
+      if (props["security-severity"]) parts.push(`**Security Severity**: ${props["security-severity"]}`);
+      if (Array.isArray(props.tags) && props.tags.length > 0) {
+        parts.push(`**Tags**: ${props.tags.join(", ")}`);
+      }
+      if (parts.length > 0) {
+        lines.push(parts.join(" | "));
+      }
+    }
+    lines.push(`**Results**: ${results.length}`);
+    lines.push("");
+    if (rule.help?.markdown) {
+      lines.push("### Query Help");
+      lines.push("");
+      lines.push(rule.help.markdown);
+      lines.push("");
+    }
+  }
+  if (results.length > 0) {
+    lines.push("### Results");
+    lines.push("");
+    lines.push("| # | File | Line | Message |");
+    lines.push("|---|------|------|---------|");
+    for (let i = 0; i < results.length; i++) {
+      const r = results[i];
+      const loc = r.locations?.[0]?.physicalLocation;
+      const uri = loc?.artifactLocation?.uri ?? "(unknown)";
+      const line = loc?.region?.startLine ?? "-";
+      const msg = r.message.text.replace(/([\\|])/g, "\\$1");
+      lines.push(`| ${i + 1} | ${uri} | ${line} | ${msg} |`);
+    }
+    lines.push("");
+  }
+  const pathResults = results.filter((r) => r.codeFlows && r.codeFlows.length > 0);
+  if (pathResults.length > 0 && rule) {
+    lines.push("### Dataflow Paths");
+    lines.push("");
+    for (let i = 0; i < pathResults.length; i++) {
+      const r = pathResults[i];
+      const loc = r.locations?.[0]?.physicalLocation;
+      const uri = loc?.artifactLocation?.uri ?? "(unknown)";
+      const line = loc?.region?.startLine ?? "?";
+      lines.push(`#### Path ${i + 1}: ${uri}:${line}`);
+      lines.push("");
+      const mermaid = sarifResultToMermaid(r, rule);
+      if (mermaid) {
+        lines.push("```mermaid");
+        lines.push(mermaid);
+        lines.push("```");
+        lines.push("");
+      }
+    }
+  }
+  return lines.join("\n");
+}
+function listSarifRules(sarif) {
+  const run = sarif.runs[0];
+  if (!run) return [];
+  const allRules = collectAllRules(run);
+  const results = run.results ?? [];
+  const toolName = run.tool.driver.name;
+  const toolVersion = run.tool.driver.version;
+  const countByRule = /* @__PURE__ */ new Map();
+  for (const r of results) {
+    countByRule.set(r.ruleId, (countByRule.get(r.ruleId) ?? 0) + 1);
+  }
+  const summaries = [];
+  const seenRuleIds = /* @__PURE__ */ new Set();
+  for (const rule of allRules) {
+    seenRuleIds.add(rule.id);
+    const props = rule.properties;
+    summaries.push({
+      kind: props?.kind,
+      name: getRuleDisplayName(rule),
+      precision: props?.precision,
+      resultCount: countByRule.get(rule.id) ?? 0,
+      ruleId: rule.id,
+      severity: props?.["security-severity"],
+      tags: Array.isArray(props?.tags) ? props.tags : void 0,
+      tool: toolName,
+      toolVersion
+    });
+  }
+  for (const [ruleId, count] of countByRule) {
+    if (!seenRuleIds.has(ruleId)) {
+      summaries.push({
+        resultCount: count,
+        ruleId,
+        tool: toolName,
+        toolVersion
+      });
+    }
+  }
+  return summaries;
+}
+function diffSarifRules(sarifA, sarifB) {
+  const rulesA = listSarifRules(sarifA);
+  const rulesB = listSarifRules(sarifB);
+  const mapA = new Map(rulesA.map((r) => [r.ruleId, r]));
+  const mapB = new Map(rulesB.map((r) => [r.ruleId, r]));
+  const addedRules = [];
+  const removedRules = [];
+  const changedRules = [];
+  const unchangedRules = [];
+  for (const [ruleId, ruleA] of mapA) {
+    const ruleB = mapB.get(ruleId);
+    if (!ruleB) {
+      removedRules.push(ruleA);
+    } else if (ruleA.resultCount !== ruleB.resultCount) {
+      changedRules.push({
+        countA: ruleA.resultCount,
+        countB: ruleB.resultCount,
+        delta: ruleB.resultCount - ruleA.resultCount,
+        ruleId
+      });
+    } else {
+      unchangedRules.push(ruleA);
+    }
+  }
+  for (const [ruleId, ruleB] of mapB) {
+    if (!mapA.has(ruleId)) {
+      addedRules.push(ruleB);
+    }
+  }
+  const runA = sarifA.runs[0];
+  const runB = sarifB.runs[0];
+  return {
+    addedRules,
+    changedRules,
+    removedRules,
+    summary: {
+      toolA: runA?.tool.driver.name,
+      toolB: runB?.tool.driver.name,
+      toolVersionA: runA?.tool.driver.version,
+      toolVersionB: runB?.tool.driver.version,
+      totalResultsA: rulesA.reduce((sum, r) => sum + r.resultCount, 0),
+      totalResultsB: rulesB.reduce((sum, r) => sum + r.resultCount, 0),
+      totalRulesA: rulesA.length,
+      totalRulesB: rulesB.length
+    },
+    unchangedRules
+  };
+}
+function computeLocationOverlap(resultA, resultB, mode = "sink") {
+  let locsA;
+  let locsB;
+  switch (mode) {
+    case "sink":
+      locsA = extractPrimaryLocations(resultA);
+      locsB = extractPrimaryLocations(resultB);
+      break;
+    case "source":
+      locsA = extractSourceLocations(resultA);
+      locsB = extractSourceLocations(resultB);
+      break;
+    case "any-location":
+      locsA = extractAllLocations(resultA);
+      locsB = extractAllLocations(resultB);
+      break;
+    case "full-path": {
+      const pathA = extractFullPathLocations(resultA);
+      const pathB = extractFullPathLocations(resultB);
+      const shared2 = findSharedLocations(pathA, pathB);
+      const allKeysA = new Set(pathA.map(locationKey));
+      const allKeysB = new Set(pathB.map(locationKey));
+      const unionSize = (/* @__PURE__ */ new Set([...allKeysA, ...allKeysB])).size;
+      const intersectionSize = [...allKeysA].filter((k) => allKeysB.has(k)).length;
+      const similarity = unionSize > 0 ? intersectionSize / unionSize : 0;
+      return {
+        overlaps: shared2.length > 0,
+        overlapMode: mode,
+        pathSimilarity: Math.round(similarity * 1e3) / 1e3,
+        sharedLocations: shared2
+      };
+    }
+    default:
+      locsA = extractPrimaryLocations(resultA);
+      locsB = extractPrimaryLocations(resultB);
+  }
+  const shared = findSharedLocations(locsA, locsB);
+  return {
+    overlaps: shared.length > 0,
+    overlapMode: mode,
+    sharedLocations: shared
+  };
+}
+
 // src/lib/session-data-manager.ts
 init_temp_dir();
 import { mkdirSync as mkdirSync6, writeFileSync as writeFileSync3 } from "fs";
@@ -183232,7 +183744,7 @@ import { randomUUID as randomUUID2 } from "crypto";
 // src/lib/sqlite-store.ts
 var import_sql_asm = __toESM(require_sql_asm(), 1);
 init_logger();
-import { mkdirSync as mkdirSync5, readFileSync as readFileSync5, renameSync, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
+import { mkdirSync as mkdirSync5, readFileSync as readFileSync6, renameSync, unlinkSync, writeFileSync as writeFileSync2 } from "fs";
 import { join as join8 } from "path";
 var SqliteStore = class _SqliteStore {
   db = null;
@@ -183257,7 +183769,7 @@ var SqliteStore = class _SqliteStore {
     mkdirSync5(this.storageDir, { recursive: true });
     const SQL = await (0, import_sql_asm.default)();
     try {
-      const fileBuffer = readFileSync5(this.dbPath);
+      const fileBuffer = readFileSync6(this.dbPath);
       this.db = new SQL.Database(fileBuffer);
     } catch {
       this.db = new SQL.Database();
@@ -183357,10 +183869,28 @@ var SqliteStore = class _SqliteStore {
       CREATE INDEX IF NOT EXISTS idx_qrc_language
         ON query_result_cache (language);
     `);
+    this.migrateAddColumn("query_result_cache", "rule_id", "TEXT");
+    this.exec(`
+      CREATE INDEX IF NOT EXISTS idx_qrc_rule_id
+        ON query_result_cache (rule_id);
+    `);
+    this.migrateAddColumn("query_result_cache", "run_id", "TEXT NOT NULL DEFAULT ''");
   }
   // ---------------------------------------------------------------------------
   // Low-level helpers
   // ---------------------------------------------------------------------------
+  /**
+   * Add a column to a table if it does not already exist (safe migration).
+   */
+  migrateAddColumn(table, column, type2) {
+    const db = this.ensureDb();
+    const result = db.exec(`PRAGMA table_info(${table})`);
+    const columns = result.length > 0 ? result[0].values.map((row) => row[1]) : [];
+    if (!columns.includes(column)) {
+      db.run(`ALTER TABLE ${table} ADD COLUMN ${column} ${type2}`);
+      this.dirty = true;
+    }
+  }
   ensureDb() {
     if (!this.db) throw new Error("SqliteStore not initialized \u2014 call initialize() first");
     return this.db;
@@ -183584,8 +184114,9 @@ var SqliteStore = class _SqliteStore {
       params.$entity_key_prefix = filter.entityKeyPrefix + "%";
     }
     if (filter?.search) {
-      conditions.push("id IN (SELECT rowid FROM annotations_fts WHERE annotations_fts MATCH $search)");
+      conditions.push("(id IN (SELECT rowid FROM annotations_fts WHERE annotations_fts MATCH $search) OR category = $search_cat COLLATE NOCASE)");
       params.$search = filter.search;
+      params.$search_cat = filter.search;
     }
     let sql = "SELECT * FROM annotations";
     if (conditions.length > 0) {
@@ -183696,11 +184227,11 @@ var SqliteStore = class _SqliteStore {
       `INSERT OR REPLACE INTO query_result_cache
        (cache_key, query_name, query_path, database_path, language, codeql_version,
         external_predicates, output_format, result_content, result_count,
-        bqrs_path, interpreted_path, execution_time_ms, created_at)
+        bqrs_path, interpreted_path, execution_time_ms, rule_id, run_id, created_at)
        VALUES ($cache_key, $query_name, $query_path, $database_path, $language,
         $codeql_version, $external_predicates, $output_format, $result_content,
         $result_count, $bqrs_path, $interpreted_path, $execution_time_ms,
-        datetime('now'))`,
+        $rule_id, $run_id, datetime('now'))`,
       {
         $cache_key: entry.cacheKey,
         $query_name: entry.queryName,
@@ -183714,7 +184245,9 @@ var SqliteStore = class _SqliteStore {
         $result_count: entry.resultCount ?? null,
         $bqrs_path: entry.bqrsPath ?? null,
         $interpreted_path: entry.interpretedPath ?? null,
-        $execution_time_ms: entry.executionTimeMs ?? null
+        $execution_time_ms: entry.executionTimeMs ?? null,
+        $rule_id: entry.ruleId ?? null,
+        $run_id: entry.runId ?? ""
       }
     );
     this.dirty = true;
@@ -183727,7 +184260,7 @@ var SqliteStore = class _SqliteStore {
     const db = this.ensureDb();
     const stmt = db.prepare(
       `SELECT cache_key, query_name, database_path, language, output_format,
-              result_count, created_at
+              result_count, rule_id, run_id, created_at
        FROM query_result_cache WHERE cache_key = $key`
     );
     stmt.bind({ $key: cacheKey2 });
@@ -183741,6 +184274,8 @@ var SqliteStore = class _SqliteStore {
         language: row.language,
         outputFormat: row.output_format,
         resultCount: row.result_count,
+        ruleId: row.rule_id ?? null,
+        runId: row.run_id ?? "",
         createdAt: row.created_at
       };
     }
@@ -183871,8 +184406,12 @@ var SqliteStore = class _SqliteStore {
       conditions.push("language = $language");
       params.$language = filter.language;
     }
+    if (filter?.ruleId) {
+      conditions.push("rule_id = $rule_id");
+      params.$rule_id = filter.ruleId;
+    }
     let sql = `SELECT cache_key, query_name, database_path, language, output_format,
-                      result_count, execution_time_ms, created_at
+                      result_count, execution_time_ms, rule_id, run_id, created_at
                FROM query_result_cache`;
     if (conditions.length > 0) {
       sql += " WHERE " + conditions.join(" AND ");
@@ -183895,6 +184434,8 @@ var SqliteStore = class _SqliteStore {
         outputFormat: row.output_format,
         resultCount: row.result_count,
         executionTimeMs: row.execution_time_ms,
+        ruleId: row.rule_id ?? null,
+        runId: row.run_id ?? "",
         createdAt: row.created_at
       });
     }
@@ -183925,6 +184466,10 @@ var SqliteStore = class _SqliteStore {
       conditions.push("database_path = $database_path");
       params.$database_path = filter.databasePath;
     }
+    if (filter?.ruleId) {
+      conditions.push("rule_id = $rule_id");
+      params.$rule_id = filter.ruleId;
+    }
     if (conditions.length === 0) return 0;
     const db = this.ensureDb();
     db.run(
@@ -184480,10 +185025,10 @@ Interpreted output saved to: ${outputFilePath}`;
         try {
           const config2 = sessionDataManager.getConfig();
           if (config2.enableAnnotationTools && outputFilePath && queryPath) {
-            const resultContent = readFileSync6(outputFilePath, "utf8");
+            const resultContent = readFileSync7(outputFilePath, "utf8");
             const codeqlVersion = getActualCodeqlVersion();
             const dbPath = params.database || "";
-            const lang = queryLanguage || "unknown";
+            const lang = queryLanguage || (dbPath ? readDatabaseMetadata(dbPath).language ?? "unknown" : "unknown");
             const extPreds = {};
             if (params.sourceFiles) extPreds.sourceFiles = params.sourceFiles;
             if (params.sourceFunction) extPreds.sourceFunction = params.sourceFunction;
@@ -184496,6 +185041,24 @@ Interpreted output saved to: ${outputFilePath}`;
               queryPath
             });
             const store = sessionDataManager.getStore();
+            let resultCount = null;
+            let ruleId = null;
+            let sarifQueryName = null;
+            if (outputFormat.includes("sarif")) {
+              try {
+                const sarif = JSON.parse(resultContent);
+                resultCount = sarif?.runs?.[0]?.results?.length ?? 0;
+                const run = sarif?.runs?.[0];
+                if (run) {
+                  const allRules = collectAllRules(run);
+                  if (allRules.length > 0) {
+                    ruleId = allRules[0].id ?? null;
+                    sarifQueryName = getRuleDisplayName(allRules[0]);
+                  }
+                }
+              } catch {
+              }
+            }
             store.putCacheEntry({
               bqrsPath,
               cacheKey: cacheKey2,
@@ -184505,9 +185068,11 @@ Interpreted output saved to: ${outputFilePath}`;
               interpretedPath: outputFilePath,
               language: lang,
               outputFormat,
-              queryName: queryName || basename4(queryPath, ".ql"),
+              queryName: sarifQueryName || queryName || basename4(queryPath, ".ql"),
               queryPath,
-              resultContent
+              resultContent,
+              resultCount,
+              ruleId
             });
             enhancedOutput += `
 Results cached with key: ${cacheKey2}`;
@@ -184574,10 +185139,94 @@ Warning: Query processing error - ${error2}`
     };
   }
 }
+function cacheDatabaseAnalyzeResults(params, logger2) {
+  try {
+    const config2 = sessionDataManager.getConfig();
+    if (!config2.enableAnnotationTools) return;
+    const outputPath = params.output;
+    const format = params.format;
+    const dbPath = params.database;
+    const queries = params.queries;
+    if (!outputPath || !format || !dbPath) return;
+    if (!format.includes("sarif")) return;
+    let resultContent;
+    try {
+      resultContent = readFileSync7(outputPath, "utf8");
+    } catch {
+      return;
+    }
+    const codeqlVersion = getActualCodeqlVersion();
+    const queryName = queries ? basename4(queries, ".qls") : "database-analyze";
+    let resultCount = null;
+    let parsedSarif = null;
+    try {
+      parsedSarif = JSON.parse(resultContent);
+      const runs = parsedSarif?.runs;
+      resultCount = runs?.[0]?.results?.length ?? 0;
+    } catch {
+    }
+    const language = params.language || (readDatabaseMetadata(dbPath).language ?? "unknown");
+    const cacheKey2 = computeQueryCacheKey({
+      codeqlVersion,
+      databasePath: dbPath,
+      outputFormat: format,
+      queryPath: queries || "database-analyze"
+    });
+    const store = sessionDataManager.getStore();
+    store.putCacheEntry({
+      cacheKey: cacheKey2,
+      codeqlVersion,
+      databasePath: dbPath,
+      interpretedPath: outputPath,
+      language,
+      outputFormat: format,
+      queryName,
+      queryPath: queries || "database-analyze",
+      resultContent,
+      resultCount
+    });
+    logger2.info(`Cached database-analyze results with key: ${cacheKey2} (${resultCount != null ? `${resultCount} results` : "result count unknown"})`);
+    if (parsedSarif) {
+      try {
+        const decomposed = decomposeSarifByRule(parsedSarif);
+        for (const [ruleId, ruleSarif] of decomposed) {
+          const ruleResults = ruleSarif.runs[0]?.results ?? [];
+          const ruleContent = JSON.stringify(ruleSarif, null, 2);
+          const ruleDef = ruleSarif.runs[0]?.tool.driver.rules?.[0];
+          const ruleDisplayName = ruleDef ? getRuleDisplayName(ruleDef) : ruleId;
+          const ruleCacheKey = computeQueryCacheKey({
+            codeqlVersion,
+            databasePath: dbPath,
+            outputFormat: format,
+            queryPath: `${queries || "database-analyze"}#${ruleId}`
+          });
+          store.putCacheEntry({
+            cacheKey: ruleCacheKey,
+            codeqlVersion,
+            databasePath: dbPath,
+            interpretedPath: outputPath,
+            language,
+            outputFormat: format,
+            queryName: ruleDisplayName,
+            queryPath: queries || "database-analyze",
+            resultContent: ruleContent,
+            resultCount: ruleResults.length,
+            ruleId
+          });
+          logger2.info(`Cached per-rule entry for ${ruleId} with key: ${ruleCacheKey} (${ruleResults.length} results)`);
+        }
+      } catch (decomposeErr) {
+        logger2.error("Failed to decompose SARIF by rule:", decomposeErr);
+      }
+    }
+  } catch (err) {
+    logger2.error("Failed to cache database-analyze results:", err);
+  }
+}
 
 // src/lib/cli-tool-registry.ts
 init_package_paths();
-import { writeFileSync as writeFileSync4, rmSync, existsSync as existsSync6, mkdirSync as mkdirSync8 } from "fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync8, realpathSync, rmSync, writeFileSync as writeFileSync4 } from "fs";
 import { delimiter as delimiter5, dirname as dirname5, isAbsolute as isAbsolute4, join as join10, resolve as resolve4 } from "path";
 
 // ../node_modules/js-yaml/dist/js-yaml.mjs
@@ -187168,6 +187817,26 @@ var safeDump = renamed("safeDump", "dump");
 
 // src/lib/cli-tool-registry.ts
 init_temp_dir();
+var databaseLocks = /* @__PURE__ */ new Map();
+function acquireDatabaseLock(dbPath) {
+  const key = dbPath;
+  const previous = databaseLocks.get(key) ?? Promise.resolve();
+  let resolveGate;
+  const gate = new Promise((resolve15) => {
+    resolveGate = resolve15;
+  });
+  databaseLocks.set(key, gate);
+  return {
+    ready: previous.then(() => {
+    }),
+    release: () => {
+      resolveGate();
+      if (databaseLocks.get(key) === gate) {
+        databaseLocks.delete(key);
+      }
+    }
+  };
+}
 var defaultCLIResultProcessor = (result, _params) => {
   if (!result.success) {
     return `Command failed (exit code ${result.exitCode || "unknown"}):
@@ -187276,8 +187945,23 @@ function registerCLITool(server, definition) {
         if (files && Array.isArray(files)) {
           positionalArgs = [...positionalArgs, ...files];
         }
-        if (file && name.startsWith("codeql_bqrs_")) {
-          positionalArgs = [...positionalArgs, file];
+        if (file !== void 0 && name.startsWith("codeql_bqrs_")) {
+          let cleanFile = Array.isArray(file) ? file.length > 0 ? String(file[0]) : "" : String(file);
+          if (cleanFile.startsWith("[") && cleanFile.endsWith("]")) {
+            try {
+              const parsed = JSON.parse(cleanFile);
+              if (Array.isArray(parsed) && parsed.length > 0) {
+                cleanFile = String(parsed[0]);
+              } else {
+                cleanFile = "";
+              }
+            } catch {
+            }
+          }
+          if (!cleanFile.trim()) {
+            throw new Error('The "file" parameter for BQRS tools must be a non-empty string path to a .bqrs file.');
+          }
+          positionalArgs = [...positionalArgs, cleanFile];
         }
         if (qlref && name === "codeql_resolve_qlref") {
           positionalArgs = [...positionalArgs, qlref];
@@ -187407,6 +188091,37 @@ function registerCLITool(server, definition) {
             }
             break;
           }
+          case "codeql_bqrs_interpret": {
+            const dbValue = options.database;
+            delete options.database;
+            if (dbValue !== void 0) {
+              const dbStr = String(dbValue).trim();
+              if (!dbStr) {
+                throw new Error('The "database" parameter must be a non-empty path to a CodeQL database.');
+              }
+              const dbPath = resolveDatabasePath(dbStr);
+              if (!options["source-archive"]) {
+                const srcZipPath = join10(dbPath, "src.zip");
+                const srcDirPath = join10(dbPath, "src");
+                if (existsSync6(srcZipPath)) {
+                  options["source-archive"] = srcZipPath;
+                } else if (existsSync6(srcDirPath)) {
+                  options["source-archive"] = srcDirPath;
+                } else {
+                  throw new Error(
+                    `CodeQL database at "${dbPath}" does not contain a source archive (expected "src.zip" file or "src" directory).`
+                  );
+                }
+              }
+              if (!options["source-location-prefix"]) {
+                const dbMeta = readDatabaseMetadata(dbPath);
+                if (dbMeta.sourceLocationPrefix) {
+                  options["source-location-prefix"] = dbMeta.sourceLocationPrefix;
+                }
+              }
+            }
+            break;
+          }
           case "codeql_query_compile":
           case "codeql_resolve_metadata":
             if (query) {
@@ -187501,7 +188216,24 @@ function registerCLITool(server, definition) {
           if (name === "codeql_test_run") {
             options["keep-databases"] = true;
           }
-          result = await executeCodeQLCommand(subcommand, options, [...positionalArgs, ...userAdditionalArgs], cwd);
+          let dbLock;
+          if (name === "codeql_database_analyze") {
+            const resolvedDb = typeof params.database === "string" ? resolveDatabasePath(params.database) : positionalArgs.length > 0 ? positionalArgs[0] : void 0;
+            if (resolvedDb) {
+              let lockKey = resolve4(resolvedDb);
+              try {
+                lockKey = realpathSync(lockKey);
+              } catch {
+              }
+              dbLock = acquireDatabaseLock(lockKey);
+              await dbLock.ready;
+            }
+          }
+          try {
+            result = await executeCodeQLCommand(subcommand, options, [...positionalArgs, ...userAdditionalArgs], cwd);
+          } finally {
+            dbLock?.release();
+          }
         } else if (command === "qlt") {
           result = await executeQLTCommand(subcommand, options, [...positionalArgs, ...userAdditionalArgs]);
         } else {
@@ -187531,6 +188263,10 @@ function registerCLITool(server, definition) {
             }
           }
         }
+        if (name === "codeql_database_analyze" && result.success && options.output) {
+          const resolvedDb = typeof params.database === "string" ? resolveDatabasePath(params.database) : params.database;
+          cacheDatabaseAnalyzeResults({ ...params, database: resolvedDb, output: options.output, format: options.format }, logger);
+        }
         const processedResult = resultProcessor(result, params);
         return {
           content: [{
@@ -187654,7 +188390,7 @@ var codeqlBqrsInfoTool = {
   command: "codeql",
   subcommand: "bqrs info",
   inputSchema: {
-    files: external_exports.array(external_exports.string()).describe("BQRS file(s) to examine"),
+    file: external_exports.string().describe("BQRS file to examine"),
     format: external_exports.enum(["text", "json"]).optional().describe("Output format: text (default) or json. Use json for machine-readable output and pagination offset computation."),
     "paginate-rows": external_exports.number().optional().describe("Compute byte offsets for pagination at intervals of this many rows. Use with --format=json. Offsets can be passed to codeql_bqrs_decode --start-at."),
     "paginate-result-set": external_exports.string().optional().describe("Compute pagination offsets only for this result set name"),
@@ -187679,7 +188415,8 @@ var codeqlBqrsInterpretTool = {
     file: external_exports.string().describe("The BQRS file to interpret"),
     format: external_exports.enum(["csv", "sarif-latest", "sarifv2.1.0", "graphtext", "dgml", "dot"]).describe("Output format: csv (comma-separated), sarif-latest/sarifv2.1.0 (SARIF), graphtext/dgml/dot (graph formats, only for @kind graph queries)"),
     output: createCodeQLSchemas.output(),
-    t: external_exports.array(external_exports.string()).describe('Query metadata key=value pairs. At least "kind" and "id" must be specified (e.g., ["kind=graph", "id=js/print-ast"])'),
+    database: external_exports.string().optional().describe("Path to the CodeQL database. When provided, auto-resolves --source-archive (for file contents/snippets) and --source-location-prefix (from codeql-database.yml metadata) so SARIF results include full source context"),
+    t: external_exports.array(external_exports.string()).describe('Query metadata key=value pairs in KEY=VALUE format. At least "kind" and "id" must be specified. Example: ["kind=problem", "id=js/sql-injection"]. Common keys: kind (problem|path-problem|graph|metric|diagnostic), id (query identifier like js/xss)'),
     "max-paths": external_exports.number().optional().describe("Maximum number of paths to produce for each alert with paths (default: 4)"),
     "sarif-add-file-contents": external_exports.boolean().optional().describe("[SARIF only] Include full file contents for all files referenced in results"),
     "sarif-add-snippets": external_exports.boolean().optional().describe("[SARIF only] Include code snippets for each location with context"),
@@ -188236,7 +188973,7 @@ var codeqlGenerateQueryHelpTool = {
 };
 
 // src/tools/codeql/list-databases.ts
-import { existsSync as existsSync8, readdirSync as readdirSync4, readFileSync as readFileSync8, statSync as statSync4 } from "fs";
+import { existsSync as existsSync8, readdirSync as readdirSync4, statSync as statSync4 } from "fs";
 import { join as join12 } from "path";
 
 // src/lib/discovery-config.ts
@@ -188259,33 +188996,6 @@ function getQueryRunResultsDirs() {
 
 // src/tools/codeql/list-databases.ts
 init_logger();
-function parseDatabaseYml(ymlPath) {
-  try {
-    const content = readFileSync8(ymlPath, "utf-8");
-    const info = {};
-    for (const line of content.split("\n")) {
-      const trimmed = line.trim();
-      const colonIdx = trimmed.indexOf(":");
-      if (colonIdx === -1) continue;
-      const key = trimmed.substring(0, colonIdx).trim();
-      const value = trimmed.substring(colonIdx + 1).trim().replace(/^["']|["']$/g, "");
-      switch (key) {
-        case "primaryLanguage":
-          info.language = value;
-          break;
-        case "cliVersion":
-          info.cliVersion = value;
-          break;
-        case "creationTime":
-          info.creationTime = value;
-          break;
-      }
-    }
-    return info;
-  } catch {
-    return {};
-  }
-}
 async function discoverDatabases(baseDirs, language) {
   const databases = [];
   for (const baseDir of baseDirs) {
@@ -188307,11 +189017,10 @@ async function discoverDatabases(baseDirs, language) {
       } catch {
         continue;
       }
-      const ymlPath = join12(entryPath, "codeql-database.yml");
-      if (!existsSync8(ymlPath)) {
+      if (!existsSync8(join12(entryPath, "codeql-database.yml")) && !existsSync8(join12(entryPath, "codeql-database.yaml"))) {
         continue;
       }
-      const metadata = parseDatabaseYml(ymlPath);
+      const metadata = readDatabaseMetadata(entryPath);
       if (language && metadata.language !== language) {
         continue;
       }
@@ -190276,7 +190985,7 @@ var codeqlResolveTestsTool = {
 };
 
 // src/tools/codeql/search-ql-code.ts
-import { closeSync as closeSync2, createReadStream as createReadStream3, fstatSync as fstatSync2, lstatSync, openSync as openSync2, readdirSync as readdirSync8, readFileSync as readFileSync12, realpathSync } from "fs";
+import { closeSync as closeSync2, createReadStream as createReadStream3, fstatSync as fstatSync2, lstatSync, openSync as openSync2, readdirSync as readdirSync8, readFileSync as readFileSync12, realpathSync as realpathSync2 } from "fs";
 import { basename as basename8, extname as extname2, join as join19, resolve as resolve9 } from "path";
 import { createInterface as createInterface3 } from "readline";
 init_logger();
@@ -190306,7 +191015,7 @@ function collectFiles(paths, extensions, fileCount) {
       if (SKIP_DIRS2.has(basename8(p))) return;
       let realPath;
       try {
-        realPath = realpathSync(p);
+        realPath = realpathSync2(p);
       } catch {
         return;
       }
@@ -190841,13 +191550,13 @@ var security_templates_default = '# Security Query Templates\n\nThis resource pr
 var server_overview_default = '# CodeQL Development MCP Server \u2014 Getting Started\n\nThis resource is the primary onboarding guide for LLM clients connecting to the CodeQL Development MCP Server. It explains what the server provides, which tools and prompts are available, and how to orchestrate common workflows.\n\n## What This Server Does\n\nThe CodeQL Development MCP Server wraps the CodeQL CLI and supporting utilities behind the Model Context Protocol (MCP). It exposes **tools** (executable actions), **prompts** (reusable workflow templates), and **resources** (reference material) that enable an LLM to develop, test, and analyze CodeQL queries without direct shell access.\n\n## Available Resources\n\nRead these resources via `resources/read` to deepen your understanding:\n\n| URI                                           | Purpose                                             |\n| --------------------------------------------- | --------------------------------------------------- |\n| `codeql://server/overview`                    | This guide \u2014 MCP server orientation                 |\n| `codeql://server/queries`                     | Bundled tools queries (PrintAST, PrintCFG, etc.)    |\n| `codeql://server/tools`                       | Complete default tool reference                     |\n| `codeql://server/prompts`                     | Complete prompt reference                           |\n| `codeql://learning/query-basics`              | QL query writing reference (syntax, metadata, etc.) |\n| `codeql://learning/test-driven-development`   | TDD theory and workflow for CodeQL                  |\n| `codeql://templates/security`                 | Security query templates (multi-language)           |\n| `codeql://patterns/performance`               | Performance profiling and optimization              |\n| `codeql://guides/query-unit-testing`          | Guide for creating and running CodeQL query tests   |\n| `codeql://guides/dataflow-migration-v1-to-v2` | Migrating from v1 to v2 dataflow API                |\n| `codeql://languages/{language}/ast`           | Language-specific AST class reference               |\n| `codeql://languages/{language}/security`      | Language-specific security patterns                 |\n\n## Quick-Start Workflows\n\n### 1. Create a New Query (TDD Approach)\n\nUse the `test_driven_development` prompt (or `ql_tdd_basic` / `ql_tdd_advanced`):\n\n1. `create_codeql_query` \u2014 scaffold query, test files, and `.qlref`\n2. `codeql_pack_install` \u2014 install pack dependencies\n3. Write test code with positive and negative cases\n4. `codeql_test_run` \u2014 run tests (expect failure initially)\n5. Implement query logic\n6. `codeql_query_compile` \u2014 validate syntax\n7. `codeql_test_run` \u2014 iterate until tests pass\n8. `codeql_test_accept` \u2014 accept correct results as baseline\n\n### 2. Understand Code Structure\n\nUse the `tools_query_workflow` prompt:\n\n1. `codeql_query_run` with `queryName="PrintAST"` \u2014 visualize the AST\n2. `codeql_query_run` with `queryName="PrintCFG"` \u2014 visualize control flow\n3. `codeql_query_run` with `queryName="CallGraphFrom"` / `"CallGraphTo"` \u2014 trace call relationships\n\n### 3. Analyze Query Quality\n\n1. `codeql_database_analyze` \u2014 run queries against a database\n2. `profile_codeql_query` or `profile_codeql_query_from_logs` \u2014 analyze performance\n3. `run_query_and_summarize_false_positives` prompt \u2014 assess precision\n4. `sarif_rank_false_positives` / `sarif_rank_true_positives` prompts \u2014 rank results\n\n### 4. Iterative Development with LSP\n\nUse the `ql_lsp_iterative_development` prompt:\n\n1. `codeql_lsp_completion` \u2014 get code completions while writing QL\n2. `codeql_lsp_definition` \u2014 navigate to symbol definitions\n3. `codeql_lsp_references` \u2014 find all references to a symbol\n4. `codeql_lsp_diagnostics` \u2014 real-time syntax and semantic validation\n\n## Tool Categories\n\nThe server provides default tools across these categories (see `codeql://server/tools` for the full reference):\n\n- **CodeQL CLI tools** \u2014 Database creation, query compilation, execution, result decoding, pack management\n- **LSP tools** \u2014 Code completion, go-to-definition, find references, diagnostics\n- **Query development tools** \u2014 Scaffolding, validation, profiling, quick evaluation, database registration\n\n## Prompt Categories\n\nThe server provides **11 prompts** (see `codeql://server/prompts` for the full reference):\n\n- **Test-driven development** \u2014 `test_driven_development`, `ql_tdd_basic`, `ql_tdd_advanced`\n- **Code understanding** \u2014 `tools_query_workflow`, `explain_codeql_query`\n- **Iterative development** \u2014 `ql_lsp_iterative_development`\n- **Documentation and quality** \u2014 `document_codeql_query`, `run_query_and_summarize_false_positives`, `sarif_rank_false_positives`, `sarif_rank_true_positives`\n- **Workshop creation** \u2014 `workshop_creation_workflow`\n\n## Key Concepts\n\n- **CodeQL database**: A relational representation of source code created by `codeql_database_create`. All queries execute against a database.\n- **QL pack**: A directory containing `codeql-pack.yml` with query or library code. Use `codeql_pack_install` to resolve dependencies.\n- **`.qlref` file**: A test reference that points from a test directory to the query being tested.\n- **`.expected` file**: The expected output of a query test. Use `codeql_test_accept` to update it when results are correct.\n- **BQRS**: Binary Query Result Sets \u2014 the native output format of `codeql_query_run`. Decode with `codeql_bqrs_decode` or interpret with `codeql_bqrs_interpret`.\n- **SARIF**: Static Analysis Results Interchange Format \u2014 the standard output format for `codeql_database_analyze`.\n\n## Supported Languages\n\nThe server supports CodeQL queries for: `actions`, `cpp`, `csharp`, `go`, `java`, `javascript`, `python`, `ruby`, `rust`, `swift`.\n';
 
 // src/resources/server-prompts.md
-var server_prompts_default = "# MCP Server Prompts\n\nThis resource provides a complete reference of the prompts exposed by the CodeQL Development MCP Server. Prompts are reusable workflow templates that guide the LLM through common CodeQL development tasks. Invoke a prompt via the MCP `prompts/get` protocol.\n\n## Prompt Reference\n\n| Prompt                                    | Description                                                                                                   |\n| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| `document_codeql_query`                   | Create or update standardized markdown documentation for a CodeQL query                                       |\n| `explain_codeql_query`                    | Generate a detailed explanation of a CodeQL query with Mermaid evaluation diagrams                            |\n| `ql_lsp_iterative_development`            | Iterative CodeQL query development using LSP tools for completion, navigation, and validation                 |\n| `ql_tdd_advanced`                         | Advanced test-driven CodeQL development with AST visualization, control flow, and call graph analysis         |\n| `ql_tdd_basic`                            | Test-driven CodeQL query development checklist \u2014 write tests first, implement query, iterate until tests pass |\n| `run_query_and_summarize_false_positives` | Run a CodeQL query and summarize its false positives by root cause                                            |\n| `sarif_rank_false_positives`              | Analyze SARIF results to identify and rank likely false positives                                             |\n| `sarif_rank_true_positives`               | Analyze SARIF results to identify and rank likely true positives                                              |\n| `test_driven_development`                 | End-to-end test-driven development workflow for CodeQL queries using MCP tools                                |\n| `tools_query_workflow`                    | Guide for using PrintAST, PrintCFG, CallGraphFrom, and CallGraphTo tool queries to understand code structure  |\n| `workshop_creation_workflow`              | Guide for creating multi-exercise CodeQL query development workshops from production-grade queries            |\n\n## Prompt Categories\n\n### Test-Driven Development\n\n- **`test_driven_development`** \u2014 The primary TDD prompt. Requires a `language` parameter and optionally accepts `queryName`. Loads the `ql-tdd-basic.prompt.md` template and walks through the complete TDD cycle: scaffold \u2192 write tests \u2192 implement \u2192 compile \u2192 test \u2192 iterate.\n- **`ql_tdd_basic`** \u2014 A standalone TDD checklist. All parameters are optional. Covers the core loop: write test cases, implement the query, run tests, iterate.\n- **`ql_tdd_advanced`** \u2014 Extends basic TDD with AST visualization (`PrintAST`), control flow graph analysis (`PrintCFG`), and call graph exploration (`CallGraphFrom`, `CallGraphTo`). Optionally accepts a `database` path for immediate analysis.\n\n### Code Understanding\n\n- **`tools_query_workflow`** \u2014 Orchestrates the four built-in tool queries (PrintAST, PrintCFG, CallGraphFrom, CallGraphTo) to explore how source code is represented in a CodeQL database. Requires `language` and `database` parameters.\n- **`explain_codeql_query`** \u2014 Produces a verbal explanation of a query's logic and generates Mermaid diagrams showing the evaluation flow. Requires `queryPath` and `language`.\n\n### Iterative Development\n\n- **`ql_lsp_iterative_development`** \u2014 Combines LSP-based code completions (`codeql_lsp_completion`), go-to-definition (`codeql_lsp_definition`), find-references (`codeql_lsp_references`), and diagnostics (`codeql_lsp_diagnostics`) for an interactive development loop.\n\n### Documentation and Quality\n\n- **`document_codeql_query`** \u2014 Generates standardized markdown documentation as a sibling `.md` file to a query. Requires `queryPath` and `language`.\n- **`run_query_and_summarize_false_positives`** \u2014 Runs a CodeQL query on a database and groups results into false-positive categories by root cause.\n- **`sarif_rank_false_positives`** / **`sarif_rank_true_positives`** \u2014 Analyze SARIF output to assess query precision by ranking results as likely true or false positives.\n\n### Workshop Creation\n\n- **`workshop_creation_workflow`** \u2014 Guides the creation of multi-exercise workshops that teach CodeQL query development. Requires `queryPath` and `language`, optionally accepts `workshopName` and `numStages`.\n\n## Related Resources\n\n- `codeql://server/overview` \u2014 MCP server orientation guide\n- `codeql://server/tools` \u2014 Complete tool reference\n- `codeql://learning/test-driven-development` \u2014 TDD theory and workflow overview\n";
+var server_prompts_default = "# MCP Server Prompts\n\nThis resource provides a complete reference of the prompts exposed by the CodeQL Development MCP Server. Prompts are reusable workflow templates that guide the LLM through common CodeQL development tasks. Invoke a prompt via the MCP `prompts/get` protocol.\n\n## Prompt Reference\n\n| Prompt                                    | Description                                                                                                   |\n| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |\n| `compare_overlapping_alerts`              | Compare CodeQL SARIF alerts across rules, files, runs, databases, or CodeQL versions                          |\n| `document_codeql_query`                   | Create or update standardized markdown documentation for a CodeQL query                                       |\n| `explain_codeql_query`                    | Generate a detailed explanation of a CodeQL query with Mermaid evaluation diagrams                            |\n| `ql_lsp_iterative_development`            | Iterative CodeQL query development using LSP tools for completion, navigation, and validation                 |\n| `ql_tdd_advanced`                         | Advanced test-driven CodeQL development with AST visualization, control flow, and call graph analysis         |\n| `ql_tdd_basic`                            | Test-driven CodeQL query development checklist \u2014 write tests first, implement query, iterate until tests pass |\n| `run_query_and_summarize_false_positives` | Run a CodeQL query and summarize its false positives by root cause                                            |\n| `sarif_rank_false_positives`              | Analyze SARIF results to identify and rank likely false positives                                             |\n| `sarif_rank_true_positives`               | Analyze SARIF results to identify and rank likely true positives                                              |\n| `test_driven_development`                 | End-to-end test-driven development workflow for CodeQL queries using MCP tools                                |\n| `tools_query_workflow`                    | Guide for using PrintAST, PrintCFG, CallGraphFrom, and CallGraphTo tool queries to understand code structure  |\n| `workshop_creation_workflow`              | Guide for creating multi-exercise CodeQL query development workshops from production-grade queries            |\n\n## Prompt Categories\n\n### Test-Driven Development\n\n- **`test_driven_development`** \u2014 The primary TDD prompt. Requires a `language` parameter and optionally accepts `queryName`. Loads the `ql-tdd-basic.prompt.md` template and walks through the complete TDD cycle: scaffold \u2192 write tests \u2192 implement \u2192 compile \u2192 test \u2192 iterate.\n- **`ql_tdd_basic`** \u2014 A standalone TDD checklist. All parameters are optional. Covers the core loop: write test cases, implement the query, run tests, iterate.\n- **`ql_tdd_advanced`** \u2014 Extends basic TDD with AST visualization (`PrintAST`), control flow graph analysis (`PrintCFG`), and call graph exploration (`CallGraphFrom`, `CallGraphTo`). Optionally accepts a `database` path for immediate analysis.\n\n### Code Understanding\n\n- **`tools_query_workflow`** \u2014 Orchestrates the four built-in tool queries (PrintAST, PrintCFG, CallGraphFrom, CallGraphTo) to explore how source code is represented in a CodeQL database. Requires `language` and `database` parameters.\n- **`explain_codeql_query`** \u2014 Produces a verbal explanation of a query's logic and generates Mermaid diagrams showing the evaluation flow. Requires `queryPath` and `language`.\n\n### Iterative Development\n\n- **`ql_lsp_iterative_development`** \u2014 Combines LSP-based code completions (`codeql_lsp_completion`), go-to-definition (`codeql_lsp_definition`), find-references (`codeql_lsp_references`), and diagnostics (`codeql_lsp_diagnostics`) for an interactive development loop.\n\n### Documentation and Quality\n\n- **`document_codeql_query`** \u2014 Generates standardized markdown documentation as a sibling `.md` file to a query. Requires `queryPath` and `language`.\n- **`run_query_and_summarize_false_positives`** \u2014 Runs a CodeQL query on a database and groups results into false-positive categories by root cause. Uses `query_results_cache_lookup`, `sarif_list_rules`, `sarif_extract_rule`, `sarif_rule_to_markdown`, and `read_database_source` for structured analysis.\n- **`sarif_rank_false_positives`** / **`sarif_rank_true_positives`** \u2014 Analyze SARIF output to assess query precision by ranking results as likely true or false positives. Uses `sarif_list_rules`, `sarif_extract_rule`, `sarif_rule_to_markdown`, `read_database_source`, `sarif_compare_alerts`, and `sarif_diff_runs` for context gathering.\n\n### Alert Analysis and Comparison\n\n- **`compare_overlapping_alerts`** \u2014 Compares CodeQL SARIF alerts across any combination of SARIF files, analysis runs, CodeQL databases, or query packs. Classifies findings as redundant, complementary, false overlap, behavioral regression, or new coverage. Uses `sarif_list_rules`, `sarif_extract_rule`, `sarif_rule_to_markdown`, `sarif_compare_alerts`, `sarif_diff_runs`, and `read_database_source` tools. Requires `sarifPathA`; optionally accepts `sarifPathB` for cross-file comparison, `ruleIdA`/`ruleIdB` to narrow to specific rules, and `databasePath` for source code context.\n\n### Workshop Creation\n\n- **`workshop_creation_workflow`** \u2014 Guides the creation of multi-exercise workshops that teach CodeQL query development. Requires `queryPath` and `language`, optionally accepts `workshopName` and `numStages`.\n\n## Related Resources\n\n- `codeql://server/overview` \u2014 MCP server orientation guide\n- `codeql://server/tools` \u2014 Complete tool reference\n- `codeql://learning/test-driven-development` \u2014 TDD theory and workflow overview\n";
 
 // src/resources/server-queries.md
-var server_queries_default = '# MCP Server Bundled Queries\n\nThis resource describes the tools queries bundled with the CodeQL Development MCP Server. These queries run via `codeql_query_run` and provide structural insight into how source code is represented in a CodeQL database. Use them to understand code structure before writing detection queries.\n\nFor general QL query writing guidance (syntax, metadata, `from`/`where`/`select`, testing conventions), see `codeql://learning/query-basics`.\n\n## Bundled Tools Queries\n\nThe server bundles four tools queries that operate on CodeQL databases:\n\n| Query           | Purpose                                           | Output Format             |\n| --------------- | ------------------------------------------------- | ------------------------- |\n| `PrintAST`      | Visualize the Abstract Syntax Tree of source code | `@kind graph` (graphtext) |\n| `PrintCFG`      | Visualize the Control Flow Graph of a function    | `@kind graph` (graphtext) |\n| `CallGraphFrom` | Show all functions called FROM a given function   | `@kind graph` (graphtext) |\n| `CallGraphTo`   | Show all call sites that call TO a given function | `@kind graph` (graphtext) |\n\nAll four queries use `@kind graph` metadata and produce output in graphtext format.\n\n## PrintAST\n\n**Purpose**: Outputs a hierarchical representation of the Abstract Syntax Tree showing parent-child relationships between declarations, statements, and expressions.\n\n**When to use**: Before writing any CodeQL query, run `PrintAST` on your test source code to understand which QL classes represent which source constructs and which predicates are available for matching.\n\n**How to run**:\n\n```text\nTool: codeql_query_run\nParameters:\n  queryName: "PrintAST"\n  queryLanguage: "<language>"\n  database: "<path-to-database>"\n  sourceFiles: "<comma-separated-filenames>"   (optional \u2014 filter to specific files)\n  format: "graphtext"\n  interpretedOutput: "<output-directory>"\n```\n\n**Output**: A tree showing each AST node with its QL class name, properties, and position in the hierarchy. This reveals exactly which QL classes and predicates to use in `from`/`where`/`select` clauses.\n\n## PrintCFG\n\n**Purpose**: Produces a Control Flow Graph representation showing the order in which statements and expressions execute, including branching paths.\n\n**When to use**: When writing queries that reason about execution order, reachability, or branching logic (e.g., "is this check always performed before this call?").\n\n**How to run**:\n\n```text\nTool: codeql_query_run\nParameters:\n  queryName: "PrintCFG"\n  queryLanguage: "<language>"\n  database: "<path-to-database>"\n  sourceFunction: "<function-name>"   (optional \u2014 target a specific function)\n  format: "graphtext"\n  interpretedOutput: "<output-directory>"\n```\n\n**Output**: Nodes representing CFG basic blocks and edges representing possible execution transitions (successor relationships).\n\n## CallGraphFrom\n\n**Purpose**: Shows all functions called FROM a specified source function \u2014 the outbound call dependencies.\n\n**When to use**: When analyzing what a function does by tracing the functions it invokes. Useful for understanding call chains and identifying potential data flow paths.\n\n**How to run**:\n\n```text\nTool: codeql_query_run\nParameters:\n  queryName: "CallGraphFrom"\n  queryLanguage: "<language>"\n  database: "<path-to-database>"\n  sourceFunction: "<function-name>"\n  format: "graphtext"\n  interpretedOutput: "<output-directory>"\n```\n\n**Output**: A graph showing each call site within the source function and the target function being called.\n\n## CallGraphTo\n\n**Purpose**: Shows all call sites that invoke a specified target function \u2014 the inbound callers.\n\n**When to use**: When performing impact analysis to understand where a function is used, or when identifying all locations that pass data to a particular sink function.\n\n**How to run**:\n\n```text\nTool: codeql_query_run\nParameters:\n  queryName: "CallGraphTo"\n  queryLanguage: "<language>"\n  database: "<path-to-database>"\n  targetFunction: "<function-name>"\n  format: "graphtext"\n  interpretedOutput: "<output-directory>"\n```\n\n**Output**: A graph showing each caller function and the specific call site where the target function is invoked.\n\n## Language Support\n\n| Language   | PrintAST | PrintCFG | CallGraphFrom | CallGraphTo |\n| ---------- | :------: | :------: | :-----------: | :---------: |\n| actions    |    \u2713     |    \u2713     |               |             |\n| cpp        |    \u2713     |    \u2713     |       \u2713       |      \u2713      |\n| csharp     |    \u2713     |    \u2713     |       \u2713       |      \u2713      |\n| go         |    \u2713     |    \u2713     |       \u2713       |      \u2713      |\n| java       |    \u2713     |    \u2713     |       \u2713       |      \u2713      |\n| javascript |    \u2713     |    \u2713     |       \u2713       |      \u2713      |\n| python     |    \u2713     |    \u2713     |       \u2713       |      \u2713      |\n| ruby       |    \u2713     |    \u2713     |       \u2713       |      \u2713      |\n| swift      |    \u2713     |    \u2713     |       \u2713       |      \u2713      |\n\nNote: The `actions` language supports PrintAST and PrintCFG only (no call graph queries).\n\n## Recommended Workflow\n\nUse the `tools_query_workflow` prompt for a guided step-by-step workflow:\n\n1. **Identify or create a database**: Use `list_codeql_databases` or `codeql_database_create`\n2. **Run PrintAST**: Understand how the source code maps to QL classes\n3. **Run PrintCFG**: Understand control flow for the functions of interest\n4. **Run CallGraphFrom / CallGraphTo**: Trace call relationships to identify sources and sinks\n5. **Write detection queries**: Use the insights from steps 2\u20134 to select the right QL classes and predicates\n\n## Related Resources\n\n- `codeql://learning/query-basics` \u2014 QL query writing reference (syntax, metadata, patterns, testing)\n- `codeql://server/overview` \u2014 MCP server orientation guide\n- `codeql://server/tools` \u2014 Complete tool reference\n- `codeql://learning/test-driven-development` \u2014 TDD workflow for CodeQL queries\n- `codeql://languages/{language}/ast` \u2014 Language-specific AST class reference\n';
+var server_queries_default = '# MCP Server Bundled Queries\n\nThis resource describes the tools queries bundled with the CodeQL Development MCP Server. These queries run via `codeql_query_run` and provide structural insight into how source code is represented in a CodeQL database. Use them to understand code structure before writing detection queries.\n\nFor general QL query writing guidance (syntax, metadata, `from`/`where`/`select`, testing conventions), see `codeql://learning/query-basics`.\n\n## Bundled Tools Queries\n\nThe server bundles five tools queries that operate on CodeQL databases:\n\n| Query             | Purpose                                                 | Output Format             |\n| ----------------- | ------------------------------------------------------- | ------------------------- |\n| `PrintAST`        | Visualize the Abstract Syntax Tree of source code       | `@kind graph` (graphtext) |\n| `PrintCFG`        | Visualize the Control Flow Graph of a function          | `@kind graph` (graphtext) |\n| `CallGraphFrom`   | Show all functions called FROM a given function         | `@kind graph` (graphtext) |\n| `CallGraphTo`     | Show all call sites that call TO a given function       | `@kind graph` (graphtext) |\n| `CallGraphFromTo` | Show calls FROM one function TO another (bidirectional) | `@kind graph` (graphtext) |\n\nAll five queries use `@kind graph` metadata and produce output in graphtext format.\n\n## PrintAST\n\n**Purpose**: Outputs a hierarchical representation of the Abstract Syntax Tree showing parent-child relationships between declarations, statements, and expressions.\n\n**When to use**: Before writing any CodeQL query, run `PrintAST` on your test source code to understand which QL classes represent which source constructs and which predicates are available for matching.\n\n**How to run**:\n\n```text\nTool: codeql_query_run\nParameters:\n  queryName: "PrintAST"\n  queryLanguage: "<language>"\n  database: "<path-to-database>"\n  sourceFiles: "<comma-separated-filenames>"   (optional \u2014 filter to specific files)\n  format: "graphtext"\n  interpretedOutput: "<output-directory>"\n```\n\n**Output**: A tree showing each AST node with its QL class name, properties, and position in the hierarchy. This reveals exactly which QL classes and predicates to use in `from`/`where`/`select` clauses.\n\n## PrintCFG\n\n**Purpose**: Produces a Control Flow Graph representation showing the order in which statements and expressions execute, including branching paths.\n\n**When to use**: When writing queries that reason about execution order, reachability, or branching logic (e.g., "is this check always performed before this call?").\n\n**How to run**:\n\n```text\nTool: codeql_query_run\nParameters:\n  queryName: "PrintCFG"\n  queryLanguage: "<language>"\n  database: "<path-to-database>"\n  sourceFunction: "<function-name>"   (optional \u2014 target a specific function)\n  format: "graphtext"\n  interpretedOutput: "<output-directory>"\n```\n\n**Output**: Nodes representing CFG basic blocks and edges representing possible execution transitions (successor relationships).\n\n## CallGraphFrom\n\n**Purpose**: Shows all functions called FROM a specified source function \u2014 the outbound call dependencies.\n\n**When to use**: When analyzing what a function does by tracing the functions it invokes. Useful for understanding call chains and identifying potential data flow paths.\n\n**How to run**:\n\n```text\nTool: codeql_query_run\nParameters:\n  queryName: "CallGraphFrom"\n  queryLanguage: "<language>"\n  database: "<path-to-database>"\n  sourceFunction: "<function-name>"\n  format: "graphtext"\n  interpretedOutput: "<output-directory>"\n```\n\n**Output**: A graph showing each call site within the source function and the target function being called.\n\n## CallGraphTo\n\n**Purpose**: Shows all call sites that invoke a specified target function \u2014 the inbound callers.\n\n**When to use**: When performing impact analysis to understand where a function is used, or when identifying all locations that pass data to a particular sink function.\n\n**How to run**:\n\n```text\nTool: codeql_query_run\nParameters:\n  queryName: "CallGraphTo"\n  queryLanguage: "<language>"\n  database: "<path-to-database>"\n  targetFunction: "<function-name>"\n  format: "graphtext"\n  interpretedOutput: "<output-directory>"\n```\n\n**Output**: A graph showing each caller function and the specific call site where the target function is invoked.\n\n## CallGraphFromTo\n\n**Purpose**: Shows the call relationship between two specific functions \u2014 whether function A calls function B (directly or transitively) and what the call path looks like.\n\n**When to use**: When investigating whether a specific source function can reach a specific sink function through the call graph. Useful for validating dataflow hypotheses before writing taint-tracking queries.\n\n**How to run**:\n\n```text\nTool: codeql_query_run\nParameters:\n  queryName: "CallGraphFromTo"\n  queryLanguage: "<language>"\n  database: "<path-to-database>"\n  sourceFunction: "<calling-function-name>"\n  targetFunction: "<called-function-name>"\n  format: "graphtext"\n  interpretedOutput: "<output-directory>"\n```\n\n**Output**: A graph showing the call path from the source function to the target function, including intermediate call sites.\n\n## Language Support\n\n| Language   | PrintAST | PrintCFG | CallGraphFrom | CallGraphTo | CallGraphFromTo |\n| ---------- | :------: | :------: | :-----------: | :---------: | :-------------: |\n| actions    |    \u2713     |    \u2713     |               |             |                 |\n| cpp        |    \u2713     |    \u2713     |       \u2713       |      \u2713      |        \u2713        |\n| csharp     |    \u2713     |    \u2713     |       \u2713       |      \u2713      |        \u2713        |\n| go         |    \u2713     |    \u2713     |       \u2713       |      \u2713      |        \u2713        |\n| java       |    \u2713     |    \u2713     |       \u2713       |      \u2713      |        \u2713        |\n| javascript |    \u2713     |    \u2713     |       \u2713       |      \u2713      |        \u2713        |\n| python     |    \u2713     |    \u2713     |       \u2713       |      \u2713      |        \u2713        |\n| ruby       |    \u2713     |    \u2713     |       \u2713       |      \u2713      |        \u2713        |\n| rust       |    \u2713     |    \u2713     |       \u2713       |      \u2713      |        \u2713        |\n| swift      |    \u2713     |    \u2713     |       \u2713       |      \u2713      |        \u2713        |\n\nNote: The `actions` language supports PrintAST and PrintCFG only (no call graph queries).\n\n## Recommended Workflow\n\nUse the `tools_query_workflow` prompt for a guided step-by-step workflow:\n\n1. **Identify or create a database**: Use `list_codeql_databases` or `codeql_database_create`\n2. **Run PrintAST**: Understand how the source code maps to QL classes\n3. **Run PrintCFG**: Understand control flow for the functions of interest\n4. **Run CallGraphFrom / CallGraphTo**: Trace call relationships to identify sources and sinks\n5. **Run CallGraphFromTo**: Verify specific source-to-sink call paths\n6. **Write detection queries**: Use the insights from steps 2\u20135 to select the right QL classes and predicates\n\n## Related Resources\n\n- `codeql://learning/query-basics` \u2014 QL query writing reference (syntax, metadata, patterns, testing)\n- `codeql://server/overview` \u2014 MCP server orientation guide\n- `codeql://server/tools` \u2014 Complete tool reference\n- `codeql://learning/test-driven-development` \u2014 TDD workflow for CodeQL queries\n- `codeql://languages/{language}/ast` \u2014 Language-specific AST class reference\n';
 
 // src/resources/server-tools.md
-var server_tools_default = '# MCP Server Tools\n\nThis resource provides a complete reference of the default tools exposed by the CodeQL Development MCP Server. These tools wrap the CodeQL CLI and supporting utilities, enabling an LLM to develop, test, and analyze CodeQL queries programmatically.\n\n## CodeQL CLI Tools\n\n| Tool                          | Description                                                                                                                  |\n| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| `codeql_bqrs_decode`          | Decode BQRS result files to human-readable formats (text, csv, json). Supports `--result-set` and `--rows` for pagination    |\n| `codeql_bqrs_info`            | Get metadata about BQRS result files: result sets, column types, row counts                                                  |\n| `codeql_bqrs_interpret`       | Interpret BQRS result files according to query metadata and generate output in specified formats (CSV, SARIF, graph formats) |\n| `codeql_database_analyze`     | Run queries or query suites against CodeQL databases. Produces evaluator logs, BQRS, and SARIF output                        |\n| `codeql_database_create`      | Create a CodeQL database from source code                                                                                    |\n| `codeql_generate_log-summary` | Create a summary of a structured JSON evaluator event log file                                                               |\n| `codeql_generate_query-help`  | Generate query help documentation from QLDoc comments                                                                        |\n| `codeql_pack_install`         | Install CodeQL pack dependencies                                                                                             |\n| `codeql_pack_ls`              | List CodeQL packs under a local directory path                                                                               |\n| `codeql_query_compile`        | Compile and validate CodeQL queries                                                                                          |\n| `codeql_query_format`         | Automatically format CodeQL source code files                                                                                |\n| `codeql_query_run`            | Execute a CodeQL query against a database                                                                                    |\n| `codeql_resolve_database`     | Resolve database path and validate database structure                                                                        |\n| `codeql_resolve_files`        | Find files in a directory tree, filtered by extension and glob patterns. Useful for discovering QL library files             |\n| `codeql_resolve_languages`    | List installed CodeQL extractor packs                                                                                        |\n| `codeql_resolve_library-path` | Resolve library path for CodeQL queries and libraries                                                                        |\n| `codeql_resolve_metadata`     | Resolve and return key-value metadata pairs from a CodeQL query source file                                                  |\n| `codeql_resolve_qlref`        | Resolve `.qlref` files to their corresponding query files                                                                    |\n| `codeql_resolve_queries`      | List available CodeQL queries found on the local filesystem                                                                  |\n| `codeql_resolve_tests`        | Resolve the local filesystem paths of unit tests and/or queries under a base directory                                       |\n| `codeql_test_accept`          | Accept new test results as the expected baseline                                                                             |\n| `codeql_test_extract`         | Extract test databases for CodeQL query tests                                                                                |\n| `codeql_test_run`             | Run CodeQL query tests                                                                                                       |\n\n## Language Server Protocol (LSP) Tools\n\n| Tool                     | Description                                                                                                                                                                  |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `codeql_lsp_completion`  | Get code completions at a cursor position in a CodeQL file                                                                                                                   |\n| `codeql_lsp_definition`  | Go to the definition of a CodeQL symbol at a given position                                                                                                                  |\n| `codeql_lsp_diagnostics` | Syntax and semantic validation of CodeQL code via the Language Server. Note: inline `ql_code` cannot resolve pack imports; use `codeql_query_compile` for files with imports |\n| `codeql_lsp_references`  | Find all references to a CodeQL symbol at a given position                                                                                                                   |\n\n## Query Development Tools\n\n| Tool                             | Description                                                                                                  |\n| -------------------------------- | ------------------------------------------------------------------------------------------------------------ |\n| `create_codeql_query`            | Create directory structure and files for a new CodeQL query with tests                                       |\n| `find_class_position`            | Find the start/end line and column of a class for quick evaluation                                           |\n| `find_codeql_query_files`        | Find and track all files and directories related to a CodeQL query, including resolved metadata              |\n| `find_predicate_position`        | Find the start/end line and column of a predicate for quick evaluation                                       |\n| `list_codeql_databases`          | List CodeQL databases discovered in configured base directories                                              |\n| `list_mrva_run_results`          | List MRVA (Multi-Repository Variant Analysis) run results with per-repo details                              |\n| `list_query_run_results`         | List query run result directories with artifact inventory. Filter by `queryName`, `language`, or `queryPath` |\n| `profile_codeql_query`           | Profile the performance of a CodeQL query run against a specific database by analyzing the evaluator log     |\n| `profile_codeql_query_from_logs` | Parse evaluator logs into a compact profile with line-indexed detail file for targeted read_file access      |\n| `quick_evaluate`                 | Quick evaluate either a class or a predicate in a CodeQL query for debugging                                 |\n| `read_database_source`           | Read source file contents from a CodeQL database source archive. Omit `filePath` to list all files           |\n| `register_database`              | Register a CodeQL database given a local path to the database directory                                      |\n| `search_ql_code`                 | Search QL source files for text or regex patterns with structured results (replaces grep for QL code)        |\n| `validate_codeql_query`          | Quick heuristic validation for CodeQL query structure (does not compile the query)                           |\n\n## Common Tool Workflows\n\n### Create and Test a Query\n\n1. `create_codeql_query` \u2014 scaffold files\n2. `codeql_pack_install` \u2014 install dependencies\n3. `codeql_query_compile` \u2014 validate syntax\n4. `codeql_test_run` \u2014 run tests\n5. `codeql_test_accept` \u2014 accept correct results\n\n### Understand Code Structure\n\n1. `codeql_query_run` with `queryName="PrintAST"` \u2014 visualize the AST\n2. `codeql_query_run` with `queryName="PrintCFG"` \u2014 visualize control flow\n3. `codeql_query_run` with `queryName="CallGraphFrom"` / `"CallGraphTo"` \u2014 trace call relationships\n\n### Profile Query Performance\n\n1. `codeql_query_run` with `evaluationOutput` \u2014 run query and capture evaluator logs\n2. `profile_codeql_query_from_logs` \u2014 analyze evaluator logs: slowest predicates, RA operations, tuple count progressions, dependencies\n\n### Discover and Search QL Code\n\n1. `codeql_resolve_files` \u2014 find QL files by extension and glob patterns in library packs\n2. `search_ql_code` \u2014 search QL source files for classes, predicates, or patterns by text/regex\n3. `codeql_lsp_definition` \u2014 navigate to the definition of a discovered symbol\n4. `codeql_lsp_references` \u2014 find all usages of a symbol across a pack\n\n### Interactive Development\n\n1. `codeql_lsp_completion` \u2014 get QL code completions\n2. `codeql_lsp_definition` \u2014 navigate to definitions\n3. `codeql_lsp_references` \u2014 find all references\n4. `codeql_lsp_diagnostics` \u2014 real-time validation\n\n## Tool Input Conventions\n\n- **LSP tools** use **0-based** line and column positions for input. Output uses 1-based `startLine`/`endLine`.\n- **`find_predicate_position`** and **`find_class_position`** return **1-based** positions.\n- **`workspace_uri`** for LSP tools must be a **plain directory path** to the pack root containing `codeql-pack.yml`, not a `file://` URI.\n\n## Related Resources\n\n- `codeql://server/overview` \u2014 MCP server orientation guide\n- `codeql://server/prompts` \u2014 Complete prompt reference\n- `codeql://learning/query-basics` \u2014 Query writing reference\n- `codeql://patterns/performance` \u2014 Performance profiling guide\n';
+var server_tools_default = '# MCP Server Tools\n\nThis resource provides a complete reference of the default tools exposed by the CodeQL Development MCP Server. These tools wrap the CodeQL CLI and supporting utilities, enabling an LLM to develop, test, and analyze CodeQL queries programmatically.\n\n## CodeQL CLI Tools\n\n| Tool                          | Description                                                                                                                  |\n| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |\n| `codeql_bqrs_decode`          | Decode BQRS result files to human-readable formats (text, csv, json). Supports `--result-set` and `--rows` for pagination    |\n| `codeql_bqrs_info`            | Get metadata about BQRS result files: result sets, column types, row counts                                                  |\n| `codeql_bqrs_interpret`       | Interpret BQRS result files according to query metadata and generate output in specified formats (CSV, SARIF, graph formats) |\n| `codeql_database_analyze`     | Run queries or query suites against CodeQL databases. Produces evaluator logs, BQRS, and SARIF output                        |\n| `codeql_database_create`      | Create a CodeQL database from source code                                                                                    |\n| `codeql_generate_log-summary` | Create a summary of a structured JSON evaluator event log file                                                               |\n| `codeql_generate_query-help`  | Generate query help documentation from QLDoc comments                                                                        |\n| `codeql_pack_install`         | Install CodeQL pack dependencies                                                                                             |\n| `codeql_pack_ls`              | List CodeQL packs under a local directory path                                                                               |\n| `codeql_query_compile`        | Compile and validate CodeQL queries                                                                                          |\n| `codeql_query_format`         | Automatically format CodeQL source code files                                                                                |\n| `codeql_query_run`            | Execute a CodeQL query against a database                                                                                    |\n| `codeql_resolve_database`     | Resolve database path and validate database structure                                                                        |\n| `codeql_resolve_files`        | Find files in a directory tree, filtered by extension and glob patterns. Useful for discovering QL library files             |\n| `codeql_resolve_languages`    | List installed CodeQL extractor packs                                                                                        |\n| `codeql_resolve_library-path` | Resolve library path for CodeQL queries and libraries                                                                        |\n| `codeql_resolve_metadata`     | Resolve and return key-value metadata pairs from a CodeQL query source file                                                  |\n| `codeql_resolve_qlref`        | Resolve `.qlref` files to their corresponding query files                                                                    |\n| `codeql_resolve_queries`      | List available CodeQL queries found on the local filesystem                                                                  |\n| `codeql_resolve_tests`        | Resolve the local filesystem paths of unit tests and/or queries under a base directory                                       |\n| `codeql_test_accept`          | Accept new test results as the expected baseline                                                                             |\n| `codeql_test_extract`         | Extract test databases for CodeQL query tests                                                                                |\n| `codeql_test_run`             | Run CodeQL query tests                                                                                                       |\n\n## Language Server Protocol (LSP) Tools\n\n| Tool                     | Description                                                                                                                                                                  |\n| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `codeql_lsp_completion`  | Get code completions at a cursor position in a CodeQL file                                                                                                                   |\n| `codeql_lsp_definition`  | Go to the definition of a CodeQL symbol at a given position                                                                                                                  |\n| `codeql_lsp_diagnostics` | Syntax and semantic validation of CodeQL code via the Language Server. Note: inline `ql_code` cannot resolve pack imports; use `codeql_query_compile` for files with imports |\n| `codeql_lsp_references`  | Find all references to a CodeQL symbol at a given position                                                                                                                   |\n\n## Query Development Tools\n\n| Tool                             | Description                                                                                                  |\n| -------------------------------- | ------------------------------------------------------------------------------------------------------------ |\n| `create_codeql_query`            | Create directory structure and files for a new CodeQL query with tests                                       |\n| `find_class_position`            | Find the start/end line and column of a class for quick evaluation                                           |\n| `find_codeql_query_files`        | Find and track all files and directories related to a CodeQL query, including resolved metadata              |\n| `find_predicate_position`        | Find the start/end line and column of a predicate for quick evaluation                                       |\n| `list_codeql_databases`          | List CodeQL databases discovered in configured base directories                                              |\n| `list_mrva_run_results`          | List MRVA (Multi-Repository Variant Analysis) run results with per-repo details                              |\n| `list_query_run_results`         | List query run result directories with artifact inventory. Filter by `queryName`, `language`, or `queryPath` |\n| `profile_codeql_query`           | Profile the performance of a CodeQL query run against a specific database by analyzing the evaluator log     |\n| `profile_codeql_query_from_logs` | Parse evaluator logs into a compact profile with line-indexed detail file for targeted read_file access      |\n| `quick_evaluate`                 | Quick evaluate either a class or a predicate in a CodeQL query for debugging                                 |\n| `read_database_source`           | Read source file contents from a CodeQL database source archive. Omit `filePath` to list all files           |\n| `register_database`              | Register a CodeQL database given a local path to the database directory                                      |\n| `search_ql_code`                 | Search QL source files for text or regex patterns with structured results (replaces grep for QL code)        |\n| `validate_codeql_query`          | Quick heuristic validation for CodeQL query structure (does not compile the query)                           |\n\n## SARIF Analysis Tools\n\n| Tool                     | Description                                                                                          |\n| ------------------------ | ---------------------------------------------------------------------------------------------------- |\n| `sarif_extract_rule`     | Extract all data for a specific rule from multi-rule SARIF. Returns a valid SARIF JSON subset        |\n| `sarif_list_rules`       | List all rules in a SARIF file with result counts, severity, precision, and tags                     |\n| `sarif_rule_to_markdown` | Convert per-rule SARIF data to markdown with Mermaid dataflow diagrams                               |\n| `sarif_compare_alerts`   | Compare code locations of two SARIF alerts for overlap (sink, source, any-location, full-path modes) |\n| `sarif_diff_runs`        | Diff two SARIF files to find added, removed, and changed rules/results across analysis runs          |\n\n## Common Tool Workflows\n\n### Create and Test a Query\n\n1. `create_codeql_query` \u2014 scaffold files\n2. `codeql_pack_install` \u2014 install dependencies\n3. `codeql_query_compile` \u2014 validate syntax\n4. `codeql_test_run` \u2014 run tests\n5. `codeql_test_accept` \u2014 accept correct results\n\n### Understand Code Structure\n\n1. `codeql_query_run` with `queryName="PrintAST"` \u2014 visualize the AST\n2. `codeql_query_run` with `queryName="PrintCFG"` \u2014 visualize control flow\n3. `codeql_query_run` with `queryName="CallGraphFrom"` / `"CallGraphTo"` \u2014 trace call relationships\n4. `codeql_query_run` with `queryName="CallGraphFromTo"` \u2014 verify source-to-sink call paths\n\n### Profile Query Performance\n\n1. `codeql_query_run` with `evaluationOutput` \u2014 run query and capture evaluator logs\n2. `profile_codeql_query_from_logs` \u2014 analyze evaluator logs: slowest predicates, RA operations, tuple count progressions, dependencies\n\n### Discover and Search QL Code\n\n1. `codeql_resolve_files` \u2014 find QL files by extension and glob patterns in library packs\n2. `search_ql_code` \u2014 search QL source files for classes, predicates, or patterns by text/regex\n3. `codeql_lsp_definition` \u2014 navigate to the definition of a discovered symbol\n4. `codeql_lsp_references` \u2014 find all usages of a symbol across a pack\n\n### Interactive Development\n\n1. `codeql_lsp_completion` \u2014 get QL code completions\n2. `codeql_lsp_definition` \u2014 navigate to definitions\n3. `codeql_lsp_references` \u2014 find all references\n4. `codeql_lsp_diagnostics` \u2014 real-time validation\n\n### Analyze and Compare Results\n\n1. `codeql_database_analyze` \u2014 run query packs and produce SARIF\n2. `sarif_list_rules` \u2014 discover rules and result counts in the SARIF\n3. `query_results_cache_lookup` with `ruleId` \u2014 find cached results by CodeQL query `@id`\n4. `sarif_extract_rule` \u2014 extract results for a specific rule from multi-rule SARIF\n5. `sarif_rule_to_markdown` \u2014 generate markdown report with Mermaid dataflow diagrams\n6. `sarif_compare_alerts` \u2014 compare two alerts for location overlap\n7. `sarif_diff_runs` \u2014 diff two SARIF files to detect behavioral changes across runs\n8. `query_results_cache_compare` with `ruleId` \u2014 compare results across databases\n\n## Tool Input Conventions\n\n- **LSP tools** use **0-based** line and column positions for input. Output uses 1-based `startLine`/`endLine`.\n- **`find_predicate_position`** and **`find_class_position`** return **1-based** positions.\n- **`workspace_uri`** for LSP tools must be a **plain directory path** to the pack root containing `codeql-pack.yml`, not a `file://` URI.\n\n## Related Resources\n\n- `codeql://server/overview` \u2014 MCP server orientation guide\n- `codeql://server/prompts` \u2014 Complete prompt reference\n- `codeql://learning/query-basics` \u2014 Query writing reference\n- `codeql://patterns/performance` \u2014 Performance profiling guide\n';
 
 // src/lib/resources.ts
 function getLearningQueryBasics() {
@@ -191710,6 +192419,9 @@ import { fileURLToPath as fileURLToPath3 } from "url";
 // src/prompts/check-for-duplicated-code.prompt.md
 var check_for_duplicated_code_prompt_default = '---\nagent: agent\n---\n\n# Check for Duplicated Code\n\nUse the MCP server tools to identify classes, modules, and predicates defined in a\n`.ql` or `.qll` file and check for possible "duplicated code," where duplicated code\nis defined to be:\n\n- Reimplementing functionality that already exists in the standard library, or shared project `.qll` files, and\n- The local definition is identical, or semantically equivalent, or superior to the library definition, or\n- The local definition could be simplified by reusing the existing definition (e.g. a base class already exists that captures some of the shared logic)\n\nHere are some examples:\n\n```ql\nimport cpp\n\n// Duplicated: `StandardNamespace` already exists in the standard library and is identical\nclass NamespaceStd extends Namespace {\n  NamespaceStd() { this.getName() = "std" }\n}\n\n// Duplicated: class should extend `Operator`, not `Function`\nclass ThrowingOperator extends Function {\n  ThrowingOperator() {\n    // Duplicated: this check is implied by using base class `Operator`\n    this.getName().matches("%operator%") and\n    and exists(ThrowExpr te |\n      // Duplicated: this is equivalent to `te.getEnclosingFunction() = this`\n      te.getParent*() = this.getAChild()\n    )\n  }\n\n  // Duplicated: member predicate `getDeclaringType()` already does this.\n  Class getDefiningClass() { ... }\n}\n\n// Duplicated: `ControlFlowNode.getASuccessor()` already exists in `cpp` and is superior\npredicate getASuccessor(Stmt a, Stmt b) {\n  exists(Block b, int i | a = b.getChild(i) and b = b.getChild(i + 1))\n}\n\n// Duplicated: prefer to import `semmle.code.cpp.controlflow.Dominance`, defined in dependency pack `cpp-all`\npredicate dominates(Block a, Block b) { ... }\n```\n\nDuplicate code removal isn\'t done arbitrarily, but for several key reasons:\n\n- **Maintainability**: Duplicated code must be maintained separately, may diverge and have different bugs\n- **Simplicity**: Relying on existing definitions reduces the amount of code to read and understand\n- **Readability**: Existing definitions map wrap complex ideas into readable names\n- **Consistency**: A single source of truth makes for a more consistent user experience across queries\n- **Completeness/Correctness**: Recreating an already-existing definition can miss edge cases, resulting in false positives or false negatives\n\n## Use This Prompt When\n\n- A query file defines a class or predicate whose name sounds generic (e.g.\n  `StandardNamespace`, `Callable`, `SecurityFeature`)\n- Refactoring a query that was written before a relevant library predicate existed\n- Reviewing a shared `.qll` file to check whether its helpers have been upstreamed\n  into the standard library in a newer CodeQL version\n- Performing a code-quality audit across a suite of custom queries\n\n## Prerequisites\n\n1. The file path of the `.ql` or `.qll` file to audit for code duplication\n2. Understand which packs are imported by `qlpack.yml`\n3. Understand where the relevant language library packs are located (e.g. `~/.codeql`)\n4. Understand where project-specific library packs are located (e.g. `$LANGUAGE/lib` or `$LANGUAGE/common`)\n5. Understand where pack-specific shared `.qll` files are located (e.g. `$PACKROOT/common/*.qll`)\n\n## Overview of the Approach\n\nThe core idea is to enumerate every top-level name defined in the file under review.\nThen, find candidate `.qll` files, based on file name and path, that are available to\nthat `.ql` file in review. Then, enumerate the top-level names in each candidate\n`.qll` file, to find potential duplicates, dive further if necessary, and then report\nthe findings as code improvement recommendations to the user.\n\n1. **Read the file** to see its imports and top-level structure\n2. **Enumerate top-level definitions** with `codeql_lsp_document_symbols`\n3. **Find available .qll files** in the `.ql` file\'s pack, and its dependencies, including the standard library\n4. **Identify promising .qll file candidates** based on their file name and path\n5. **Enumerate top-level definitions in candidate `.qll` files** with `codeql_lsp_document_symbols`\n6. **Detect overlap, comparing definitions if unclear** (e.g. by using `find_predicate_position` and `find_class_position` tools)\n7. **Report findings** as a set of recommendations to the user about which definitions could be improved, by reusing which existing definitions\n\n## Step 1: Read the File and Note Its Imports\n\n```text\nTool: read_file\nParameters:\n  file_path: /path/to/query.ql\n  start_line: 1\n  end_line: 60   # enough to see all imports\n```\n\nRecord every `import` statement. These are the namespaces the standard library\nexposes; duplication is only meaningful for libraries that are already imported (or\neasily importable).\n\n## Step 2: Enumerate Top-Level Definitions\n\nUse `codeql_lsp_document_symbols` to retrieve every class, predicate, and module\ndefined at the top level of the file in a single call:\n\n```text\nTool: codeql_lsp_document_symbols\nParameters:\n  file_path: /path/to/query.ql\n  names_only: true                    # provides significantly smaller response payload\n  workspace_uri: /path/to/pack-root   # directory containing codeql-pack.yml\n```\n\nThe response contains a `symbols` array. Each entry has:\n\n- `name` \u2014 the identifier as written in source\n- `kind` \u2014 numeric SymbolKind (5 = Class, 12 = Function/predicate, 2 = Module, etc.)\n- `range` \u2014 the full definition range (0-based lines)\n- `selectionRange` \u2014 the range of just the name token\n- `children` \u2014 nested members (for classes and modules)\n\nTop-level symbols are the root nodes of the array; `children` hold member\npredicates and fields.\n\n## Step 3. Read the filesystem to find candidate library `.qll` files\n\nRun the tool `codeql_resolve_library-path` with the given ql query file to find where\nthe available library sources live.\n\nFor each source root, run `find $ROOT -name "*.qll"` to find all `.qll` files\navailable in that pack. Do not preemptively filter this list of qll files. The names\nof the files may be broad or nondescriptive. Read all file names for each project to\nunderstand its structure and responsibilities before proceeding to step 3d.\n\nChoose promising candidate `.qll` files you found in the previous step. Pick\ncandidates that may potentially define behavior relevant to the current query and its\nenumerated definitions, based on the candidate filename, path, and priority.\n\nPrioritize as follows:\n\n- `.qll` files in the same directory as the query file have the absolute highest priority\n- `.qll` files in the same pack have the next extremely high priority\n- `.qll` files in project-specific library packs have the very high priority\n- `.qll` files in downloaded direct dependencies have standard priority\n- `.qll` files in transitive dependencies have the least priority.\n\n## Step 4: Identify candidate terms in the candidate library `.qll` files\n\nEnumerate the top-level definitions for each candidate `.qll` file using the tool\n`codeql_lsp_document_symbols` again. Some top levels may clearly match the name or\npurpose of a definition in the query file, while others may only appear as possibly\nrelated.\n\n```text\nTool: codeql_lsp_document_symbols\nParameters:\n  file_path: /path/to/library/file.qll\n  workspace_uri: /path/to/pack-root\n```\n\n## Step 5: Perform final overlap analysis\n\nFor each promising candidate, identify the predicate or class definitions that may overlap. One definition will be in the query file (`.ql`) and the other will be in the library file (`.qll`).\n\nUsing the tools `find_predicate_position` and `find_class_position`, you can retrieve the full definition of each predicate or class, and compare them to determine whether they are identical, equivalent, overlapping, or if one is a superior implementation that could be reused by the query file.\n\nDutifully analyze whether the shared library file definition would reduce code duplication in the categories identified before: maintenance, simplicity, readability, consistency, and completeness/correctness. Consider contextual factors such as comments explaining why the local definition differs from the library one, or whether the local definition is a thin wrapper around the library definition that adds value (e.g. by improving naming or adding extra checks).\n\nDo not go on a wild goose chase trying to find every possible overlap. Consider the likelihood of overlap based on the broadness of functionality, and the value that would be brought be reuse. Do not waste significant time on unimportant or unlikely overlaps.\n\n## Step 6: Report Findings\n\nFor each duplicate found, report:\n\n| Local name          | Local file    | import path                      | Notes      |\n| ------------------- | ------------- | -------------------------------- | ---------- |\n| `StandardNamespace` | `query.ql:42` | already imported in `import cpp` | Identical  |\n| `myHelper`          | `query.ql:80` | `import myproject.Helpers`       | Equivalent |\n| `myHelper`          | `query.ql:80` | `import myproject.Helpers`       | Equivalent |\n\nRecommend one of:\n\n- **Replace**: remove the local definition and use the standard definition directly instead\n- **Integrate**: refactor and simplify the local definition by making use of the standard definition\n- **Annotate**: add comments to the local definition to explain how it differs from the standard definition and why the duplication is necessary\n\nAdditionally, report if any issues came up in using the tools, or finding the qll files.\n\nFor each concept for which no duplicate was found, provide at most a **brief** description of what the concept is. Do not provide a long detailed explanation of a non-finding.\n\n# Conclusion\n\nDo **not** perform any updates to any code during this analysis.\n\nAs you work through completing this task, ask yourself:\n\n- Have I changed any code, even though that was not my task, or am I about to? Stop, do not change any code!\n- Did I sufficiently analyze the definitions such that I likely found most overlapping definitions?\n- Will my suggestions improve the maintainability, simplicity, readability, consistency, or completeness/correctness of the codebase?\n- Did I report my findings clearly?\n- Did I use the suggested LLM tools to their fullest extent?\n- Did I follow the steps in the recommended order, and not skip any steps?\n- Did I report any issues I had in finding the relevant `.qll` files, or using the tools to analyze definitions?\n';
 
+// src/prompts/compare-overlapping-alerts.prompt.md
+var compare_overlapping_alerts_prompt_default = '---\nagent: agent\n---\n\n# Compare Overlapping Alerts\n\n## Goal\n\nCompare CodeQL SARIF alerts across **any combination** of SARIF files, analysis runs, CodeQL databases, CodeQL versions, or query packs. Detect overlapping, redundant, or divergent results and classify each finding to guide query development decisions.\n\nThis workflow supports:\n\n- Comparing alerts from **different rules** in the same SARIF (e.g., standard vs custom queries)\n- Comparing alerts from **different SARIF files** (e.g., two separate `codeql database analyze` runs)\n- Checking for **behavioral deviations** across CodeQL CLI versions or database rebuilds\n- Detecting **redundancy** between custom query packs and standard query packs\n\n## Workflow\n\n### Step 1: Discover available rules\n\nUse #sarif_list_rules on each SARIF source to understand what rules and result counts are present. When comparing within a single file, call it once:\n\n```\nsarif_list_rules(sarifPath="{{sarifPathA}}")\n```\n\nWhen comparing two different SARIF files, call it on both:\n\n```\nsarif_list_rules(sarifPath="{{sarifPathA}}")\nsarif_list_rules(sarifPath="{{sarifPathB}}")\n```\n\nThe response includes `ruleId`, `resultCount`, `kind`, `precision`, `severity`, and `tags` for each rule.\n\n### Step 2: Choose a comparison strategy\n\nDepending on the use case, choose the appropriate strategy:\n\n**Same-file, different rules** (custom vs standard overlap):\n\n- Use #sarif_extract_rule to extract each rule\'s results from the same file\n- Use #sarif_compare_alerts to compare individual alert pairs\n\n**Different files, same rule** (behavioral deviation across runs):\n\n- Use #sarif_diff_runs to get a high-level diff of added/removed/changed rules\n- For changed rules, use #sarif_extract_rule on both files and compare results\n\n**Different files, different rules** (cross-pack overlap):\n\n- Use #sarif_extract_rule on each file with the respective rule IDs\n- Use #sarif_compare_alerts with different `sarifPath` values for alertA and alertB\n\n### Step 3: Diff runs (for cross-run comparison)\n\nWhen comparing two analysis runs, start with a structural diff:\n\n```\nsarif_diff_runs(\n  sarifPathA="{{sarifPathA}}",\n  sarifPathB="{{sarifPathB}}",\n  labelA="baseline",\n  labelB="comparison"\n)\n```\n\nThis returns `addedRules`, `removedRules`, `changedRules` (with result count deltas), and `unchangedRules`. Focus investigation on `changedRules` and `addedRules`.\n\n### Step 4: Extract and visualize results\n\nFor rules of interest, extract full results and generate markdown reports:\n\n```\nsarif_extract_rule(sarifPath="{{sarifPathA}}", ruleId="<ruleId>")\nsarif_rule_to_markdown(sarifPath="{{sarifPathA}}", ruleId="<ruleId>")\n```\n\nThe markdown report includes:\n\n- Rule summary with severity, precision, tags\n- Query help text\n- Results table with file, line, and message\n- Mermaid `flowchart LR` diagrams for each dataflow path\n\n### Step 5: Compare specific alerts for overlap\n\nUse #sarif_compare_alerts to compare individual results between rules or files. Each alert specifier can reference a **different SARIF file**:\n\n```\nsarif_compare_alerts(\n  alertA={sarifPath="{{sarifPathA}}", ruleId="<ruleIdA>", resultIndex=0},\n  alertB={sarifPath="{{sarifPathB}}", ruleId="<ruleIdB>", resultIndex=0},\n  overlapMode="sink"\n)\n```\n\nIf sink overlap is found, re-check with `source` and `full-path` modes:\n\n- **sink**: same primary alert location (file + line + column range overlap)\n- **source**: same dataflow source (first step in threadFlow)\n- **any-location**: any location in alertA overlaps any location in alertB (including intermediate steps)\n- **full-path**: Jaccard similarity on dataflow path steps; `pathSimilarity` 0.0\u20131.0\n\n### Step 6: Read source code context\n\nFor each overlapping pair, use #read_database_source to read the relevant source file from the CodeQL database. **Note**: the `filePath` parameter uses the URI from the SARIF alert location, not an absolute path:\n\n```\nread_database_source(databasePath="{{databasePath}}", filePath="<uri-from-alert>")\n```\n\nRead 10\u201320 lines around the flagged location for context. When comparing across databases, read from each database separately.\n\n### Step 7: Classify each finding\n\nFor each overlapping or divergent pair, classify as:\n\n1. **Redundant** \u2014 Same problem, same or very similar code path (`pathSimilarity > 0.7`). One query subsumes the other.\n   - **Action**: add a `not` exclusion predicate to the more specific query, or configure alert suppression\n\n2. **Complementary** \u2014 Same sink but different source models or taint configurations (`pathSimilarity < 0.3`). Both queries add defensive value.\n   - **Action**: keep both; document the overlap in query help text\n\n3. **False overlap** \u2014 Same file and line but semantically different issues (different arguments, different properties).\n   - **Action**: no change needed\n\n4. **Behavioral regression** \u2014 A rule that previously found N results now finds fewer (or zero). Visible via #sarif_diff_runs `changedRules`.\n   - **Action**: investigate query or library changes between CodeQL versions\n\n5. **New coverage** \u2014 A rule appears in `addedRules` or has increased results. Indicates improved detection.\n   - **Action**: review new results for false positive rate\n\n### Step 8: Produce summary\n\nCreate a structured summary with:\n\n- SARIF sources compared (file paths, labels, tool versions)\n- Total alerts per rule per source\n- Run diff summary: added/removed/changed rule counts\n- For each overlap: classification, both alert messages, shared locations, path similarity\n- Recommendations: which queries to prioritize, exclusion predicates to add, follow-up analysis needed\n\n## Notes\n\n- `ruleId` values correspond to CodeQL query `@id` metadata (e.g., `js/sql-injection`)\n- #sarif_compare_alerts supports **cross-file** comparison: `alertA.sarifPath` and `alertB.sarifPath` can be different files\n- #sarif_diff_runs compares by rule ID, not by result content \u2014 use it for high-level structural comparison, then drill into individual alerts\n- #read_database_source requires the database path \u2014 pass via the `databasePath` parameter or resolve it with #list_codeql_databases\n- When working from cached results, substitute `cacheKey` for `sarifPath` in all tool calls\n- Path similarity above 0.7 usually indicates redundancy; below 0.3 indicates complementary coverage\n- For cross-version comparison, run `codeql database analyze` with two different CodeQL CLI versions against the same database, save both SARIF files, and use #sarif_diff_runs to compare\n';
+
 // src/prompts/document-codeql-query.prompt.md
 var document_codeql_query_prompt_default = '---\nagent: agent\n---\n\n# Document a CodeQL Query\n\nThis prompt guides you through creating or updating documentation for a CodeQL query file. The documentation is stored as a sibling file to the query with a standardized markdown format.\n\n## Purpose\n\nThe `document_codeql_query` prompt creates/updates **query documentation files** for a specific version of a CodeQL query. Documentation files are stored alongside the query file and provide concise yet comprehensive information about what the query does.\n\nFor creating **workshop learning content** with detailed explanations and visual diagrams, use the `explain_codeql_query` prompt instead.\n\n## Required Inputs\n\n- **queryPath**: Path to the CodeQL query file (`.ql` or `.qlref`)\n- **language**: Target programming language (actions, cpp, csharp, go, java, javascript, python, ruby, rust, swift)\n\n## Documentation File Conventions\n\n### File Location and Naming\n\nFor a query file `QueryFileBaseName.ql`, the documentation file should be:\n\n- **Primary**: `QueryFileBaseName.md` (markdown format, preferred)\n- **Legacy**: `QueryFileBaseName.qhelp` (XML-based query help format)\n\nDocumentation files are **siblings** to the query file (same directory).\n\n### Handling Existing Documentation\n\n1. **No documentation exists**: Create new `QueryFileBaseName.md` file\n2. **`.md` file exists**: Update the existing markdown file\n3. **`.qhelp` file exists**: Use #codeql_generate_query-help tool to convert to markdown, then update\n\n## Workflow Checklist\n\nUse the following MCP server tools to gather context before creating documentation:\n\n### Phase 1: Query Discovery\n\n- [ ] **Step 1: Locate query files**\n  - Tool: #find_codeql_query_files\n  - Parameters: `queryPath` = provided query path\n  - Gather: Query source file path, existing documentation files, test files\n  - Check: Does `QueryFileBaseName.md` or `QueryFileBaseName.qhelp` exist?\n\n- [ ] **Step 2: Read query metadata**\n  - Tool: #codeql_resolve_metadata\n  - Parameters: `query` = query file path\n  - Gather: @name, @description, @kind, @id, @tags, @precision, @severity\n\n### Phase 2: Convert Existing qhelp (if needed)\n\n- [ ] **Step 3: Convert qhelp to markdown** (only if `.qhelp` exists)\n  - Tool: #codeql_generate_query-help\n  - Parameters: `query` = query file path, `format` = "markdown"\n  - Use output as starting point for updated documentation\n\n### Phase 3: Gather Query Context\n\n- [ ] **Step 4: Validate query structure**\n  - Tool: #validate_codeql_query\n  - Parameters: `query` = query source code\n  - Gather: Structural validation, suggestions\n  - Note: This is a heuristic check only \u2014 for full validation, use #codeql_query_compile\n\n- [ ] **Step 5: Explore query types** (if deeper understanding needed)\n  - Tool: #codeql_lsp_definition \u2014 navigate to class/predicate definitions\n  - Tool: #codeql_lsp_completion \u2014 explore member predicates on types used in the query\n  - Parameters: `file_path`, `line` (0-based), `character` (0-based), `workspace_uri` (pack root)\n  - Run #codeql_pack_install first \u2014 LSP tools require resolved dependencies\n\n- [ ] **Step 6: Run tests** (if tests exist from Step 1)\n  - Tool: #codeql_test_run\n  - Parameters: `tests` = test directories\n  - Gather: Pass/fail status, confirms query behavior\n\n### Phase 4: Create/Update Documentation\n\nBased on gathered context, create or update the documentation file.\n\n## Documentation Format\n\nThe documentation file (`QueryFileBaseName.md`) should follow this standardized format with these sections:\n\n### Section 1: Title and Description\n\n- H1 heading with the query name from @name metadata\n- One paragraph description from @description, expanded if needed\n\n### Section 2: Metadata Table\n\nA table with these rows:\n\n- ID: The @id value in backticks\n- Kind: The @kind value (problem, path-problem, etc.)\n- Severity: The @severity value\n- Precision: The @precision value\n- Tags: The @tags values\n\n### Section 3: Overview\n\nConcise explanation of what vulnerability/issue this query detects and why it matters. 2-4 sentences.\n\n### Section 4: Recommendation\n\nBrief guidance on how developers should fix issues flagged by this query. Include code patterns to use or avoid.\n\n### Section 5: Example\n\nTwo subsections:\n\n- **Vulnerable Code**: A code block showing a pattern that would be flagged by this query\n- **Fixed Code**: A code block showing the corrected version of the code\n\nUse the appropriate language identifier for the code blocks (e.g., `javascript`, `python`, `java`).\n\n### Section 6: References\n\nA list of links to:\n\n- Relevant CWE if security query\n- Relevant documentation or standards\n- CodeQL documentation for related concepts\n\n## Output Actions\n\nAfter generating documentation content:\n\n1. **For new documentation**: Create the file at `[QueryDirectory]/QueryFileBaseName.md`\n2. **For existing `.md` file**: Update the file with new content, preserving any custom sections\n3. **For existing `.qhelp` file**: Create new `.md` file (keeping `.qhelp` for backward compatibility)\n\n## Important Notes\n\n- **Be concise**: Documentation should be brief but complete. This is reference documentation, not tutorial content.\n- **Keep it current**: Documentation should reflect the current behavior of the query.\n- **Use examples from tests**: If unit tests exist, use those code patterns as examples.\n- **Standard format**: Always use the format above for consistency across all query documentation.\n- **Metadata accuracy**: Ensure documented metadata matches actual query metadata.\n- **For workshops**: Use `explain_codeql_query` prompt when creating workshop content that requires deeper explanations and visual diagrams.\n';
 
@@ -191729,13 +192441,13 @@ var ql_tdd_advanced_prompt_default = '---\nagent: agent\n---\n\n# Advanced Test-
 var ql_tdd_basic_prompt_default = '---\nagent: agent\n---\n\n# Test-Driven CodeQL Query Development Checklist\n\nUse this checklist to guide test-driven development of CodeQL queries. Follow the TDD cycle: write tests first, implement query logic, and iterate until tests pass.\n\nFor advanced techniques including AST/CFG visualization, see: `codeql://prompts/ql-tdd-advanced`\nFor detailed guidance, reference the MCP resource: `codeql://learning/test-driven-development`\n\n## TDD Workflow Checklist\n\n### Phase 1: Project Setup\n\n- [ ] **Create Query Structure**\n  - Tool: #create_codeql_query\n  - Specify: basePath, queryName, language, description (optional)\n  - Creates: src/QueryName/QueryName.ql, test/QueryName/QueryName.qlref, test/QueryName/test-code-file\n  - The .qlref file will contain the relative path: `QueryName/QueryName.ql`\n  - Verify: directory structure follows CodeQL conventions with intermediate directories\n\n- [ ] **Install Pack Dependencies**\n  - Tool: #codeql_pack_install\n  - Install src pack dependencies\n  - Install test pack dependencies\n  - Verify: imports resolve without errors\n\n### Phase 2: Test Design (Red Phase)\n\n- [ ] **Design Test Cases**\n  - Create positive test cases (should match)\n  - Create negative test cases (should not match)\n  - Create edge case tests\n  - Document expected behavior in comments\n\n- [ ] **Define Expected Results**\n  - Create .expected file with anticipated matches\n  - Specify exact match locations (file, line, column)\n  - Include expected alert messages\n\n- [ ] **Extract Test Database**\n  - Tool: #codeql_test_extract\n  - Extract database from test code\n  - Verify: .testproj directory created\n\n### Phase 3: Analysis and Understanding\n\n- [ ] **Analyze Test Code AST**\n  - Tool: #codeql_query_run with queryName: "PrintAST"\n  - Use format: "graphtext" for @kind graph queries\n  - Review AST structure and identify relevant classes\n\n- [ ] **Explore Available Classes and Predicates**\n  - Tool: #codeql_lsp_completion at the position in the `from` clause\n  - Parameters: `file_path`, `line` (0-based), `character` (0-based)\n  - Set `workspace_uri` to the pack root directory (containing `codeql-pack.yml`)\n  - Request completions after a dot (e.g., `pw.`) to see member predicates with docs\n  - Tip: Run #codeql_pack_install first \u2014 LSP tools require resolved dependencies\n\n- [ ] **Navigate to Type Definitions**\n  - Tool: #codeql_lsp_definition on a class or predicate name\n  - Parameters: `file_path`, `line` (0-based), `character` (0-based), `workspace_uri`\n  - Returns file URI and line range \u2014 even into library pack files\n  - Read the definition source to understand available member predicates\n  - Tool: #codeql_lsp_references to find usage examples across the pack\n\n  For the full iterative LSP workflow, see: `codeql://prompts/ql_lsp_iterative_development`\n\n- [ ] **Reference Language Documentation**\n  - Resource: `codeql://languages/{language}/ast`\n  - Resource: `codeql://languages/{language}/security` (if applicable)\n  - Identify AST classes and predicates needed\n\n### Phase 4: Implementation (Green Phase)\n\n- [ ] **Write Query Metadata**\n  - Add @name annotation\n  - Add @description annotation\n  - Add @kind annotation (problem, path-problem, graph, etc.)\n  - Add @id and other required metadata\n\n- [ ] **Implement Query Logic**\n  - Import required libraries\n  - Define necessary classes (if any)\n  - Define helper predicates\n  - Implement main query clause\n\n- [ ] **Compile Query**\n  - Tool: #codeql_query_compile\n  - Fix any compilation errors\n  - Verify: query compiles successfully\n\n- [ ] **Run Tests**\n  - Tool: #codeql_test_run\n  - Compare actual vs expected results\n  - If tests fail: adjust query logic and recompile\n  - If tests pass: proceed to validation\n\n### Phase 5: Validation and Acceptance\n\n- [ ] **Verify Test Results**\n  - Review all test matches\n  - Confirm no false positives\n  - Confirm no false negatives\n  - Check edge cases behave correctly\n\n- [ ] **Accept Test Results** (only when correct)\n  - Tool: #codeql_test_accept\n  - Update .expected files\n  - Commit accepted results\n\n### Phase 6: Refactoring and Enhancement\n\n- [ ] **Refactor Query**\n  - Improve code clarity\n  - Extract common logic to predicates\n  - Add code comments and documentation\n  - Tool: #codeql_query_format for consistent formatting\n\n- [ ] **Optimize Performance** (if needed)\n  - Run with evaluator-log enabled\n  - Tool: #profile_codeql_query_from_logs\n  - Resource: `codeql://patterns/performance`\n  - Optimize expensive operations\n\n- [ ] **Generate Documentation**\n  - Tool: #codeql_generate_query_help\n  - Review and enhance QLDoc comments\n  - Document query purpose and limitations\n\n### Phase 7: Additional Testing\n\n- [ ] **Add More Test Cases**\n  - Identify additional scenarios\n  - Add tests for new edge cases\n  - Extract new test databases\n  - Run expanded test suite\n\n- [ ] **Validate Against Real Code** (optional)\n  - Tool: #codeql_database_create for real codebase\n  - Tool: #codeql_query_run against real database\n  - Review results for false positives/negatives\n\n## Quick Command Reference\n\n### Essential Tools\n\n```typescript\n// Create query structure\ncreate_codeql_query: {\n  basePath: "/path/to/query/base",\n  queryName: "MySecurityQuery",\n  language: "javascript",\n  description: "Detects security vulnerability X"\n}\n\n// Install dependencies\ncodeql_pack_install: {\n  packPath: "/path/to/pack"\n}\n\n// Extract test database\ncodeql_test_extract: {\n  testPath: "/path/to/test/QueryName",\n  searchPath: "/path/to/base"\n}\n\n// Analyze AST (for @kind graph queries)\ncodeql_query_run: {\n  queryName: "PrintAST",\n  queryLanguage: "javascript",\n  database: "/path/to/test.testproj",\n  format: "graphtext",\n  interpretedOutput: "/path/to/ast-output/"\n}\n\n// Compile query\ncodeql_query_compile: {\n  query: "/path/to/Query.ql",\n  searchPath: "/path/to/base",\n  checkOnly: true\n}\n\n// Run tests\ncodeql_test_run: {\n  testPath: "/path/to/test/Query.qlref",\n  searchPath: "/path/to/base"\n}\n\n// Accept results\ncodeql_test_accept: {\n  testPath: "/path/to/test/Query",\n  searchPath: "/path/to/base"\n}\n```\n\n## TDD Principles to Remember\n\n1. **Red \u2192 Green \u2192 Refactor**: Always start with failing tests\n2. **Test First**: Write tests before implementation\n3. **Small Steps**: Make minimal changes to pass each test\n4. **Frequent Testing**: Run tests after each change\n5. **One Concept Per Test**: Each test should verify one behavior\n6. **Keep Tests Simple**: Test code should be easy to understand\n7. **Refactor Confidently**: Tests enable safe refactoring\n\n## Common Pitfalls to Avoid\n\n- \u274C Writing query before tests\n- \u274C Accepting test results without verification\n- \u274C Skipping compilation step\n- \u274C Not using PrintAST to understand test code\n- \u274C Not using #codeql_lsp_completion to discover available types\n- \u274C Not setting `workspace_uri` when using LSP tools (completions will be empty)\n- \u274C Creating tests that are too complex\n- \u274C Ignoring false positives in results\n- \u274C Not refactoring after tests pass\n\n## Success Criteria\n\nYour query development is complete when:\n\n- \u2705 All tests pass\n- \u2705 No false positives in test results\n- \u2705 No false negatives (all expected cases caught)\n- \u2705 Query compiles without errors or warnings\n- \u2705 Code is well-documented with QLDoc comments\n- \u2705 Performance is acceptable\n- \u2705 Edge cases are covered by tests\n- \u2705 Query follows CodeQL best practices\n\n## Next Steps After Completion\n\n1. **Integration Testing**: Test against real codebases\n2. **Peer Review**: Have another developer review the query\n3. **Documentation**: Update project documentation\n4. **Regression Testing**: Add to CI/CD pipeline\n5. **Monitor Performance**: Track query performance over time\n';
 
 // src/prompts/run-query-and-summarize-false-positives.prompt.md
-var run_query_and_summarize_false_positives_prompt_default = '---\nagent: agent\n---\n\n# Run a query and describe its false positives\n\n## Task\n\nHelp a developer discover what kinds of false positives are produced by their current CodeQL query, and which of those false positive cases are most common.\n\n### Task steps:\n\n1. Read the provided CodeQL query to understand what patterns it is designed to detect.\n2. Discover the results of this query on a real database, by:\n   - Running the tool #list_query_run_results to find existing runs for this query\n   - If no existing runs are found, run the query on a relevant database using #codeql_query_run tool\n3. Analyze and group the results into what appear to be similar types of results. This may mean:\n   - Grouping results in the same file\n   - Grouping results that reference the same elements\n   - Grouping results with similar messages\n4. For each group, explore the actual code for a sample of alerts in that group, using the #read_database_source tool to triage the results and determine which groups appear to be false positives\n5. For each false positive case discovered in this exploration, group them into categories of similar root causes. For example, a query might not properly account for unreachable code, or there may be a commonly used library that violates the query\'s assumptions but is actually safe.\n6. Explain these results to the user in order of most common to least common, so they can understand where their query may need improvement to reduce false positives.\n\n## Input Context\n\nYou will be provided with:\n\n- **Query Path**: The path to the CodeQL query\n\n## Analysis Guidelines\n\n### Exploring code paths\n\nThe tool #read_database_source can be used to read the code of a particular finding. A good strategy to explore the code paths of a finding is:\n\n1. Read in the immediate context of the violation.\n   - Some queries may depend on later context (e.g., an "unused variable" may only be used after its declaration)\n   - Some queries may depend on earlier context (e.g., "mutex not initialized" requires observing code that ran before the violation)\n   - Some queries may rely on exploring other function calls.\n2. Read the interprocedural context of the violation.\n   - If understanding a violation requires checking other source locations, read the beginning of the file to find what it imports, and then read those imported files to find the relevant code.\n   - Selectively scan interprocedural paths. A false positive that requires tremendous code exploration to verify is less problematic than a false positive that only requires checking a small amount of code to verify.\n3. Stop early.\n   - Grouping the potential false positive cases is more important than exhaustively verifying every single finding.\n   - A common false positive likely introduces some false positives that are very hard to verify, so it is usually better to focus on simple cases first.\n   - Truly hard-to-verify false positive cases are often in code that users don\'t expect to be conducive to static analysis, and query authors often don\'t expect their queries to work well in those cases.\n   - Suggest a chainsaw approach rather than a scalpel - if a result may be a false positive, identify some simple heuristics to eliminate all such complex cases, even if such a heuristic could introduce false negatives.\n\n### What Makes a Result Likely to be a False Positive?\n\n1. **Pattern Mismatches**\n   - Query pattern doesn\'t accurately match the actual code behavior\n   - Missing context that would show the code is safe\n   - Overly broad query logic catching benign variations\n\n2. **Safe Code Patterns**\n   - Code includes proper validation before the flagged operation\n   - Results in test code, example code, or mock implementations\n   - Variable/function names suggesting test/example context (e.g., `testFunc`, `exampleVar`, `mockData`)\n   - Defensive programming patterns present but not recognized by query\n\n3. **Context Indicators**\n   - File paths suggesting test/example files (e.g., `test/`, `examples/`, `mock/`)\n   - Comments indicating intentional patterns or safe usage\n   - Framework-specific patterns that are safe in context\n\n4. **Technical Factors**\n   - Type mismatches that make the vulnerability impossible\n   - Control flow that prevents exploitation\n   - Data flow interrupted by sanitization not captured in query\n\n### Important Constraints\n\n- **Be objective**: Don\'t be influenced by variable/function naming suggesting importance (e.g., "prodOnly" vs "test")\n- **Require evidence**: Base conclusions on actual code patterns, not assumptions\n- **Mark uncertainty**: Use lower confidence scores when code snippets are missing\n- **Avoid false confidence**: If you cannot determine FP status, mark confidence as low\n\n## Output Format\n\nReturn a JSON array of false-positive _groups_, ordered by the estimated prevalence or importance of the false-positive pattern (highest first):\n\n```json\n[\n  {\n    "groupLabel": "Test and example code with safe validation",\n    "patternSummary": "Results where the flagged operation occurs in test/example files and is always preceded by input validation.",\n    "resultCount": 23,\n    "estimatedFpProportion": 0.9,\n    "confidence": 0.85,\n    "commonRootCause": "The query does not recognize common test/example locations or custom validation helpers as making the pattern safe.",\n    "sampleResults": [\n      {\n        "sourceFile": "results-1.sarif",\n        "resultIndex": 42,\n        "ruleId": "query-id",\n        "message": { "text": "original result message" },\n        "locations": []\n      }\n    ],\n    "reasoning": "Based on manual inspection of several alerts in this group: (1) results are consistently located under \'test/\' or \'examples/\' directories, (2) there is clear validation before the flagged operation, and (3) the query does not model the custom validation helpers used in these files."\n  }\n]\n```\n\n### Field Descriptions\n\n- **groupLabel**: Short human-readable name for the false-positive category.\n- **patternSummary**: One-sentence description of the common pattern shared by results in this group.\n- **resultCount**: Number of SARIF results that belong to this group.\n- **estimatedFpProportion**: Estimated proportion of results in this group that are false positives (0.0\u20131.0).\n- **confidence**: Confidence in the group-level assessment (see guidelines below).\n- **commonRootCause**: Why the query produces false positives for this pattern.\n- **sampleResults**: A small representative sample of results illustrating the pattern.\n- **reasoning**: Detailed explanation of how the FP determination was made.\n\n### Confidence Score Guidelines\n\n- **0.8-1.0**: Strong evidence of FP (e.g., test code with clear safety patterns)\n- **0.6-0.8**: Good evidence of FP (e.g., defensive patterns present)\n- **0.4-0.6**: Moderate evidence of FP (e.g., context suggests safety but not conclusive)\n- **0.2-0.4**: Weak evidence of FP (e.g., minor indicators, missing code snippets)\n- **0.0-0.2**: Minimal evidence (uncertain, need more information)\n\n## Examples\n\n### High-Confidence FP Group Example\n\n```json\n{\n  "groupLabel": "Sanitised inputs in test harnesses",\n  "patternSummary": "Results in test files where sanitizeInput() is called before the database query.",\n  "resultCount": 15,\n  "estimatedFpProportion": 0.95,\n  "confidence": 0.9,\n  "commonRootCause": "Query does not model sanitizeInput() as a sanitizer.",\n  "sampleResults": [\n    {\n      "sourceFile": "results-1.sarif",\n      "resultIndex": 7,\n      "ruleId": "js/sql-injection",\n      "message": { "text": "Potential SQL injection" },\n      "locations": []\n    }\n  ],\n  "reasoning": "False positive group: (1) File paths like \'test/unit/database-mock.test.js\' indicate test code, (2) Query doesn\'t recognize that \'sanitizeInput()\' is called before database query, (3) All 15 results share this pattern."\n}\n```\n\n### Low-Confidence FP Group Example\n\n```json\n{\n  "groupLabel": "File utility handlers with unclear validation",\n  "patternSummary": "Results in src/utils/ files where path validation may or may not be present.",\n  "resultCount": 4,\n  "estimatedFpProportion": 0.5,\n  "confidence": 0.3,\n  "commonRootCause": "Unclear whether custom path validation is sufficient.",\n  "sampleResults": [\n    {\n      "sourceFile": "results-1.sarif",\n      "resultIndex": 22,\n      "ruleId": "js/path-injection",\n      "message": { "text": "Potential path traversal" },\n      "locations": []\n    }\n  ],\n  "reasoning": "Possibly false positive: (1) No code snippets available in SARIF, (2) File path \'src/utils/fileHandler.js\' doesn\'t indicate test code, (3) Cannot verify if proper path validation exists. Low confidence due to missing context."\n}\n```\n\n## Processing Instructions\n\n1. **Review SARIF results** and group them by common patterns\n2. **Analyze available context** (code snippets, file paths, messages) for each group\n3. **Compare against query logic** to understand what pattern was detected\n4. **Identify FP indicators** based on guidelines above\n5. **Assign group-level confidence scores** reflecting evidence strength\n6. **Write clear reasoning** for each group explaining the assessment\n7. **Sort groups** by estimated prevalence / importance (descending)\n\n## Important Notes\n\n- A result should belong to at most one FP group\n- When in doubt, prefer lower confidence scores\n- Missing code snippets should always reduce confidence\n- Test/example code is more likely to be FP but not always\n- Focus on technical evidence, not code naming conventions\n';
+var run_query_and_summarize_false_positives_prompt_default = '---\nagent: agent\n---\n\n# Run a query and describe its false positives\n\n## Task\n\nHelp a developer discover what kinds of false positives are produced by their current CodeQL query, and which of those false positive cases are most common.\n\n### Task steps:\n\n1. Read the provided CodeQL query to understand what patterns it is designed to detect.\n2. Discover the results of this query on a real database, by:\n   - Using #query_results_cache_lookup with `ruleId` (the query\'s `@id` metadata) to find previously cached results\n   - Running #list_query_run_results to find existing run artifacts\n   - If no existing results are found, run the query using #codeql_query_run with `format: "sarif-latest"` to produce SARIF output (results are auto-cached with `ruleId` for later lookup)\n3. Use #sarif_list_rules on the SARIF output to confirm rule metadata and result counts. For multi-rule SARIF, use #sarif_extract_rule to isolate the specific query\'s results.\n4. Use #sarif_rule_to_markdown to generate a structured overview with a results table and Mermaid dataflow diagrams for path-problem results. This gives an immediate visual summary of all findings.\n5. Analyze and group the results into what appear to be similar types of results. This may mean:\n   - Grouping results in the same file\n   - Grouping results that reference the same elements\n   - Grouping results with similar messages\n6. For each group, explore the actual code for a sample of alerts using #read_database_source with the `filePath` from the SARIF alert URI and 10\u201320 lines of context around the flagged location.\n7. For each false positive case discovered, group them into categories of similar root causes.\n8. Explain these results to the user in order of most common to least common.\n\n## Input Context\n\nYou will be provided with:\n\n- **Query Path**: The path to the CodeQL query\n\n## Analysis Guidelines\n\n### Exploring code paths\n\nUse #read_database_source with the `filePath` from the SARIF alert\'s `physicalLocation.artifactLocation.uri` and the `databasePath` of the CodeQL database. Read 10\u201320 lines around the flagged location:\n\n1. Read in the immediate context of the violation.\n   - Some queries may depend on later context (e.g., an "unused variable" may only be used after its declaration)\n   - Some queries may depend on earlier context (e.g., "mutex not initialized" requires observing code that ran before the violation)\n   - Some queries may rely on exploring other function calls.\n2. Read the interprocedural context of the violation.\n   - If understanding a violation requires checking other source locations, read the beginning of the file to find what it imports, and then read those imported files to find the relevant code.\n   - Selectively scan interprocedural paths. A false positive that requires tremendous code exploration to verify is less problematic than a false positive that only requires checking a small amount of code to verify.\n3. Stop early.\n   - Grouping the potential false positive cases is more important than exhaustively verifying every single finding.\n   - A common false positive likely introduces some false positives that are very hard to verify, so it is usually better to focus on simple cases first.\n   - Truly hard-to-verify false positive cases are often in code that users don\'t expect to be conducive to static analysis, and query authors often don\'t expect their queries to work well in those cases.\n   - Suggest a chainsaw approach rather than a scalpel - if a result may be a false positive, identify some simple heuristics to eliminate all such complex cases, even if such a heuristic could introduce false negatives.\n\n### What Makes a Result Likely to be a False Positive?\n\n1. **Pattern Mismatches**\n   - Query pattern doesn\'t accurately match the actual code behavior\n   - Missing context that would show the code is safe\n   - Overly broad query logic catching benign variations\n\n2. **Safe Code Patterns**\n   - Code includes proper validation before the flagged operation\n   - Results in test code, example code, or mock implementations\n   - Variable/function names suggesting test/example context (e.g., `testFunc`, `exampleVar`, `mockData`)\n   - Defensive programming patterns present but not recognized by query\n\n3. **Context Indicators**\n   - File paths suggesting test/example files (e.g., `test/`, `examples/`, `mock/`)\n   - Comments indicating intentional patterns or safe usage\n   - Framework-specific patterns that are safe in context\n\n4. **Technical Factors**\n   - Type mismatches that make the vulnerability impossible\n   - Control flow that prevents exploitation\n   - Data flow interrupted by sanitization not captured in query\n\n### Important Constraints\n\n- **Be objective**: Don\'t be influenced by variable/function naming suggesting importance (e.g., "prodOnly" vs "test")\n- **Require evidence**: Base conclusions on actual code patterns, not assumptions\n- **Mark uncertainty**: Use lower confidence scores when code snippets are missing\n- **Avoid false confidence**: If you cannot determine FP status, mark confidence as low\n\n## Output Format\n\nReturn a JSON array of false-positive _groups_, ordered by the estimated prevalence or importance of the false-positive pattern (highest first):\n\n```json\n[\n  {\n    "groupLabel": "Test and example code with safe validation",\n    "patternSummary": "Results where the flagged operation occurs in test/example files and is always preceded by input validation.",\n    "resultCount": 23,\n    "estimatedFpProportion": 0.9,\n    "confidence": 0.85,\n    "commonRootCause": "The query does not recognize common test/example locations or custom validation helpers as making the pattern safe.",\n    "sampleResults": [\n      {\n        "sourceFile": "results-1.sarif",\n        "resultIndex": 42,\n        "ruleId": "query-id",\n        "message": { "text": "original result message" },\n        "locations": []\n      }\n    ],\n    "reasoning": "Based on manual inspection of several alerts in this group: (1) results are consistently located under \'test/\' or \'examples/\' directories, (2) there is clear validation before the flagged operation, and (3) the query does not model the custom validation helpers used in these files."\n  }\n]\n```\n\n### Field Descriptions\n\n- **groupLabel**: Short human-readable name for the false-positive category.\n- **patternSummary**: One-sentence description of the common pattern shared by results in this group.\n- **resultCount**: Number of SARIF results that belong to this group.\n- **estimatedFpProportion**: Estimated proportion of results in this group that are false positives (0.0\u20131.0).\n- **confidence**: Confidence in the group-level assessment (see guidelines below).\n- **commonRootCause**: Why the query produces false positives for this pattern.\n- **sampleResults**: A small representative sample of results illustrating the pattern.\n- **reasoning**: Detailed explanation of how the FP determination was made.\n\n### Confidence Score Guidelines\n\n- **0.8-1.0**: Strong evidence of FP (e.g., test code with clear safety patterns)\n- **0.6-0.8**: Good evidence of FP (e.g., defensive patterns present)\n- **0.4-0.6**: Moderate evidence of FP (e.g., context suggests safety but not conclusive)\n- **0.2-0.4**: Weak evidence of FP (e.g., minor indicators, missing code snippets)\n- **0.0-0.2**: Minimal evidence (uncertain, need more information)\n\n## Examples\n\n### High-Confidence FP Group Example\n\n```json\n{\n  "groupLabel": "Sanitised inputs in test harnesses",\n  "patternSummary": "Results in test files where sanitizeInput() is called before the database query.",\n  "resultCount": 15,\n  "estimatedFpProportion": 0.95,\n  "confidence": 0.9,\n  "commonRootCause": "Query does not model sanitizeInput() as a sanitizer.",\n  "sampleResults": [\n    {\n      "sourceFile": "results-1.sarif",\n      "resultIndex": 7,\n      "ruleId": "js/sql-injection",\n      "message": { "text": "Potential SQL injection" },\n      "locations": []\n    }\n  ],\n  "reasoning": "False positive group: (1) File paths like \'test/unit/database-mock.test.js\' indicate test code, (2) Query doesn\'t recognize that \'sanitizeInput()\' is called before database query, (3) All 15 results share this pattern."\n}\n```\n\n### Low-Confidence FP Group Example\n\n```json\n{\n  "groupLabel": "File utility handlers with unclear validation",\n  "patternSummary": "Results in src/utils/ files where path validation may or may not be present.",\n  "resultCount": 4,\n  "estimatedFpProportion": 0.5,\n  "confidence": 0.3,\n  "commonRootCause": "Unclear whether custom path validation is sufficient.",\n  "sampleResults": [\n    {\n      "sourceFile": "results-1.sarif",\n      "resultIndex": 22,\n      "ruleId": "js/path-injection",\n      "message": { "text": "Potential path traversal" },\n      "locations": []\n    }\n  ],\n  "reasoning": "Possibly false positive: (1) No code snippets available in SARIF, (2) File path \'src/utils/fileHandler.js\' doesn\'t indicate test code, (3) Cannot verify if proper path validation exists. Low confidence due to missing context."\n}\n```\n\n## Processing Instructions\n\n1. **Review SARIF results** and group them by common patterns\n2. **Analyze available context** (code snippets, file paths, messages) for each group\n3. **Compare against query logic** to understand what pattern was detected\n4. **Identify FP indicators** based on guidelines above\n5. **Assign group-level confidence scores** reflecting evidence strength\n6. **Write clear reasoning** for each group explaining the assessment\n7. **Sort groups** by estimated prevalence / importance (descending)\n\n## Important Notes\n\n- A result should belong to at most one FP group\n- When in doubt, prefer lower confidence scores\n- Missing code snippets should always reduce confidence\n- Test/example code is more likely to be FP but not always\n- Focus on technical evidence, not code naming conventions\n';
 
 // src/prompts/sarif-rank-false-positives.prompt.md
-var sarif_rank_false_positives_prompt_default = '---\nagent: agent\n---\n\n# Evaluate SARIF Results for False Positives\n\n## Task\n\nAnalyze SARIF results from a CodeQL query and identify the most likely **False Positives (FPs)** - results that incorrectly flag benign code as problematic.\n\n## Input Context\n\nYou will be provided with:\n\n- **Query ID**: The CodeQL query/rule identifier\n- **Query Name**: Human-readable name of the query\n- **Query Content**: Full CodeQL query implementation\n- **SARIF Results**: Array of results to analyze\n- **Code Snippets**: When available, code snippets from SARIF physical locations\n\n## Analysis Guidelines\n\n### What Makes a Result Likely to be a False Positive?\n\n1. **Pattern Mismatches**\n   - Query pattern doesn\'t accurately match the actual code behavior\n   - Missing context that would show the code is safe\n   - Overly broad query logic catching benign variations\n\n2. **Safe Code Patterns**\n   - Code includes proper validation before the flagged operation\n   - Results in test code, example code, or mock implementations\n   - Variable/function names suggesting test/example context (e.g., `testFunc`, `exampleVar`, `mockData`)\n   - Defensive programming patterns present but not recognized by query\n\n3. **Context Indicators**\n   - File paths suggesting test/example files (e.g., `test/`, `examples/`, `mock/`)\n   - Comments indicating intentional patterns or safe usage\n   - Framework-specific patterns that are safe in context\n\n4. **Technical Factors**\n   - Type mismatches that make the vulnerability impossible\n   - Control flow that prevents exploitation\n   - Data flow interrupted by sanitization not captured in query\n\n### Important Constraints\n\n- **Be objective**: Don\'t be influenced by variable/function naming suggesting importance (e.g., "prodOnly" vs "test")\n- **Require evidence**: Base conclusions on actual code patterns, not assumptions\n- **Mark uncertainty**: Use lower confidence scores when code snippets are missing\n- **Avoid false confidence**: If you cannot determine FP status, mark confidence as low\n\n### When Code Snippets Are Missing\n\nIf SARIF results lack `physicalLocation.region.snippet` or `contextRegion`:\n\n- **Lower confidence scores** (typically 0.3-0.5 instead of 0.6-0.9)\n- **Note the limitation** in reasoning\n- **Rely more on**:\n  - Result message text\n  - File path analysis\n  - Query logic understanding\n\n## Output Format\n\nReturn a JSON array of ranked results, ordered by FP likelihood (highest first):\n\n```json\n[\n  {\n    "ruleId": "query-id",\n    "message": { "text": "original result message" },\n    "locations": [...],\n    "confidence": 0.85,\n    "reasoning": "This appears to be a false positive because: (1) the file path \'test/examples/mock-data.js\' indicates test code, (2) variable name \'testInput\' suggests this is test data, (3) the query doesn\'t account for the validation on line X.",\n    "sourceFile": "results-1.sarif",\n    "resultIndex": 42\n  }\n]\n```\n\n### Confidence Score Guidelines\n\n- **0.8-1.0**: Strong evidence of FP (e.g., test code with clear safety patterns)\n- **0.6-0.8**: Good evidence of FP (e.g., defensive patterns present)\n- **0.4-0.6**: Moderate evidence of FP (e.g., context suggests safety but not conclusive)\n- **0.2-0.4**: Weak evidence of FP (e.g., minor indicators, missing code snippets)\n- **0.0-0.2**: Minimal evidence (uncertain, need more information)\n\n## Examples\n\n### High-Confidence FP Example\n\n```json\n{\n  "ruleId": "js/sql-injection",\n  "message": { "text": "Potential SQL injection" },\n  "confidence": 0.9,\n  "reasoning": "False positive: (1) File path \'test/unit/database-mock.test.js\' indicates test code, (2) Query doesn\'t recognize that \'sanitizeInput()\' function is called before database query, (3) Variable name \'mockUserInput\' suggests test data. Missing code snippet limits certainty to 0.9 instead of 1.0."\n}\n```\n\n### Low-Confidence FP Example\n\n```json\n{\n  "ruleId": "js/path-injection",\n  "message": { "text": "Potential path traversal" },\n  "confidence": 0.3,\n  "reasoning": "Possibly a false positive: (1) No code snippets available in SARIF, (2) File path \'src/utils/fileHandler.js\' doesn\'t indicate test code, (3) Cannot verify if proper path validation exists. Low confidence due to missing context."\n}\n```\n\n## Processing Instructions\n\n1. **Review each SARIF result** in the provided array\n2. **Analyze available context** (code snippets, file paths, messages)\n3. **Compare against query logic** to understand what pattern was detected\n4. **Identify FP indicators** based on guidelines above\n5. **Assign confidence score** reflecting evidence strength\n6. **Write clear reasoning** explaining your assessment\n7. **Sort results** by confidence score (descending)\n8. **Return top N results** as requested (or all if N not specified)\n\n## Important Notes\n\n- A result should never appear in both FP and TP rankings\n- When in doubt, prefer lower confidence scores\n- Missing code snippets should always reduce confidence\n- Test/example code is more likely to be FP but not always\n- Focus on technical evidence, not code naming conventions\n';
+var sarif_rank_false_positives_prompt_default = '---\nagent: agent\n---\n\n# Evaluate SARIF Results for False Positives\n\n## Task\n\nAnalyze SARIF results from a CodeQL query and identify the most likely **False Positives (FPs)** - results that incorrectly flag benign code as problematic.\n\n## Input Context\n\nYou will be provided with:\n\n- **Query ID**: The CodeQL query/rule identifier\n- **Query Name**: Human-readable name of the query\n- **Query Content**: Full CodeQL query implementation\n- **SARIF Results**: Array of results to analyze\n- **Code Snippets**: When available, code snippets from SARIF physical locations\n\n## Recommended Tool Usage\n\nUse these tools to gather context for each result:\n\n1. **#sarif_list_rules** \u2014 Discover all rules and result counts in the SARIF data. Helps scope the analysis.\n2. **#sarif_extract_rule** \u2014 Extract results for the specific query `@id` from multi-rule SARIF. Returns a clean SARIF subset.\n3. **#sarif_rule_to_markdown** \u2014 Generate a structured markdown report with results table and Mermaid dataflow diagrams. Provides an immediate visual overview of all findings.\n4. **#read_database_source** \u2014 Read source code from the CodeQL database using the `filePath` from the SARIF alert URI. Read 10\u201320 lines around each flagged location for context.\n5. **#query_results_cache_lookup** with `ruleId` \u2014 Check if results for this query are already cached from previous runs.\n6. **#sarif_compare_alerts** \u2014 When the same codebase has results from both standard and custom queries, compare alert locations to distinguish unique findings from overlapping ones.\n7. **#sarif_diff_runs** \u2014 Compare against a baseline SARIF run to identify new results vs previously known findings.\n\n## Analysis Guidelines\n\n### What Makes a Result Likely to be a False Positive?\n\n1. **Pattern Mismatches**\n   - Query pattern doesn\'t accurately match the actual code behavior\n   - Missing context that would show the code is safe\n   - Overly broad query logic catching benign variations\n\n2. **Safe Code Patterns**\n   - Code includes proper validation before the flagged operation\n   - Results in test code, example code, or mock implementations\n   - Variable/function names suggesting test/example context (e.g., `testFunc`, `exampleVar`, `mockData`)\n   - Defensive programming patterns present but not recognized by query\n\n3. **Context Indicators**\n   - File paths suggesting test/example files (e.g., `test/`, `examples/`, `mock/`)\n   - Comments indicating intentional patterns or safe usage\n   - Framework-specific patterns that are safe in context\n\n4. **Technical Factors**\n   - Type mismatches that make the vulnerability impossible\n   - Control flow that prevents exploitation\n   - Data flow interrupted by sanitization not captured in query\n\n### Important Constraints\n\n- **Be objective**: Don\'t be influenced by variable/function naming suggesting importance (e.g., "prodOnly" vs "test")\n- **Require evidence**: Base conclusions on actual code patterns, not assumptions\n- **Mark uncertainty**: Use lower confidence scores when code snippets are missing\n- **Avoid false confidence**: If you cannot determine FP status, mark confidence as low\n\n### When Code Snippets Are Missing\n\nIf SARIF results lack `physicalLocation.region.snippet` or `contextRegion`:\n\n- **Lower confidence scores** (typically 0.3-0.5 instead of 0.6-0.9)\n- **Note the limitation** in reasoning\n- **Rely more on**:\n  - Result message text\n  - File path analysis\n  - Query logic understanding\n\n## Output Format\n\nReturn a JSON array of ranked results, ordered by FP likelihood (highest first):\n\n```json\n[\n  {\n    "ruleId": "query-id",\n    "message": { "text": "original result message" },\n    "locations": [...],\n    "confidence": 0.85,\n    "reasoning": "This appears to be a false positive because: (1) the file path \'test/examples/mock-data.js\' indicates test code, (2) variable name \'testInput\' suggests this is test data, (3) the query doesn\'t account for the validation on line X.",\n    "sourceFile": "results-1.sarif",\n    "resultIndex": 42\n  }\n]\n```\n\n### Confidence Score Guidelines\n\n- **0.8-1.0**: Strong evidence of FP (e.g., test code with clear safety patterns)\n- **0.6-0.8**: Good evidence of FP (e.g., defensive patterns present)\n- **0.4-0.6**: Moderate evidence of FP (e.g., context suggests safety but not conclusive)\n- **0.2-0.4**: Weak evidence of FP (e.g., minor indicators, missing code snippets)\n- **0.0-0.2**: Minimal evidence (uncertain, need more information)\n\n## Examples\n\n### High-Confidence FP Example\n\n```json\n{\n  "ruleId": "js/sql-injection",\n  "message": { "text": "Potential SQL injection" },\n  "confidence": 0.9,\n  "reasoning": "False positive: (1) File path \'test/unit/database-mock.test.js\' indicates test code, (2) Query doesn\'t recognize that \'sanitizeInput()\' function is called before database query, (3) Variable name \'mockUserInput\' suggests test data. Missing code snippet limits certainty to 0.9 instead of 1.0."\n}\n```\n\n### Low-Confidence FP Example\n\n```json\n{\n  "ruleId": "js/path-injection",\n  "message": { "text": "Potential path traversal" },\n  "confidence": 0.3,\n  "reasoning": "Possibly a false positive: (1) No code snippets available in SARIF, (2) File path \'src/utils/fileHandler.js\' doesn\'t indicate test code, (3) Cannot verify if proper path validation exists. Low confidence due to missing context."\n}\n```\n\n## Processing Instructions\n\n1. **Review each SARIF result** in the provided array\n2. **Analyze available context** (code snippets, file paths, messages)\n3. **Compare against query logic** to understand what pattern was detected\n4. **Identify FP indicators** based on guidelines above\n5. **Assign confidence score** reflecting evidence strength\n6. **Write clear reasoning** explaining your assessment\n7. **Sort results** by confidence score (descending)\n8. **Return top N results** as requested (or all if N not specified)\n\n## Important Notes\n\n- A result should never appear in both FP and TP rankings\n- When in doubt, prefer lower confidence scores\n- Missing code snippets should always reduce confidence\n- Test/example code is more likely to be FP but not always\n- Focus on technical evidence, not code naming conventions\n';
 
 // src/prompts/sarif-rank-true-positives.prompt.md
-var sarif_rank_true_positives_prompt_default = '---\nagent: agent\n---\n\n# Evaluate SARIF Results for True Positives\n\n## Task\n\nAnalyze SARIF results from a CodeQL query and identify the most likely **True Positives (TPs)** - results that correctly identify real security vulnerabilities or code quality issues.\n\n## Input Context\n\nYou will be provided with:\n\n- **Query ID**: The CodeQL query/rule identifier\n- **Query Name**: Human-readable name of the query\n- **Query Content**: Full CodeQL query implementation\n- **SARIF Results**: Array of results to analyze\n- **Code Snippets**: When available, code snippets from SARIF physical locations\n\n## Analysis Guidelines\n\n### What Makes a Result Likely to be a True Positive?\n\n1. **Pattern Matches**\n   - Query pattern accurately identifies the problematic code behavior\n   - Result shows clear evidence of the vulnerability or issue\n   - Code matches the exact pattern the query was designed to detect\n\n2. **Vulnerable Code Patterns**\n   - User input flows to dangerous sink without proper sanitization\n   - Missing security checks or validation\n   - Incorrect use of security-sensitive APIs\n   - Clear violation of security best practices\n\n3. **Production Code Context**\n   - File paths suggesting production code (e.g., `src/`, `lib/`, `app/`)\n   - NOT in test/example directories\n   - Function/variable names suggesting real business logic\n   - Code appears to be part of actual application functionality\n\n4. **Technical Factors**\n   - Data flow from untrusted source to dangerous operation\n   - Missing or insufficient sanitization\n   - Exploitable control flow\n   - Real security or quality implications\n\n### Important Constraints\n\n- **Be objective**: Don\'t be influenced by variable/function naming suggesting importance\n- **Require evidence**: Base conclusions on actual vulnerability patterns, not assumptions\n- **Mark uncertainty**: Use lower confidence scores when code snippets are missing\n- **Avoid false confidence**: If you cannot determine TP status, mark confidence as low\n- **Consider false positives**: Be skeptical - real vulnerabilities often have subtle mitigations\n\n### When Code Snippets Are Missing\n\nIf SARIF results lack `physicalLocation.region.snippet` or `contextRegion`:\n\n- **Lower confidence scores** (typically 0.3-0.5 instead of 0.6-0.9)\n- **Note the limitation** in reasoning\n- **Rely more on**:\n  - Result message text\n  - File path analysis\n  - Query logic understanding\n\n## Output Format\n\nReturn a JSON array of ranked results, ordered by TP likelihood (highest first):\n\n```json\n[\n  {\n    "ruleId": "query-id",\n    "message": { "text": "original result message" },\n    "locations": [...],\n    "confidence": 0.85,\n    "reasoning": "This appears to be a true positive because: (1) the file path \'src/api/user-controller.js\' indicates production code, (2) user input from request parameter flows directly to SQL query without sanitization, (3) no validation or prepared statement usage detected.",\n    "sourceFile": "results-1.sarif",\n    "resultIndex": 15\n  }\n]\n```\n\n### Confidence Score Guidelines\n\n- **0.8-1.0**: Strong evidence of TP (e.g., clear vulnerability with exploit path)\n- **0.6-0.8**: Good evidence of TP (e.g., production code with problematic pattern)\n- **0.4-0.6**: Moderate evidence of TP (e.g., pattern matches but context unclear)\n- **0.2-0.4**: Weak evidence of TP (e.g., possible issue but missing context)\n- **0.0-0.2**: Minimal evidence (uncertain, need more information)\n\n## Examples\n\n### High-Confidence TP Example\n\n```json\n{\n  "ruleId": "js/sql-injection",\n  "message": { "text": "Unsanitized user input in SQL query" },\n  "confidence": 0.9,\n  "reasoning": "True positive: (1) File path \'src/controllers/UserController.js\' indicates production code, (2) User input from req.query.userId flows directly to SQL query string concatenation, (3) No prepared statements or sanitization visible in code snippet, (4) Classic SQL injection pattern. Confidence is 0.9 not 1.0 due to possibility of sanitization elsewhere in call chain."\n}\n```\n\n### Moderate-Confidence TP Example\n\n```json\n{\n  "ruleId": "js/path-injection",\n  "message": { "text": "Potential path traversal vulnerability" },\n  "confidence": 0.6,\n  "reasoning": "Likely true positive: (1) File path \'src/utils/fileHandler.js\' suggests production utility code, (2) User-controlled filename parameter used in fs.readFile(), (3) No visible path validation, but code snippet is limited. Moderate confidence due to incomplete context - may have validation in calling code."\n}\n```\n\n### Low-Confidence TP Example (Missing Snippets)\n\n```json\n{\n  "ruleId": "java/unsafe-deserialization",\n  "message": { "text": "Unsafe deserialization of user data" },\n  "confidence": 0.4,\n  "reasoning": "Possibly a true positive: (1) File path \'src/main/java/com/app/handlers/DataHandler.java\' indicates production code, (2) Message suggests unsafe deserialization pattern, (3) No code snippets available in SARIF to verify actual vulnerability or confirm absence of mitigations. Confidence is low due to missing context."\n}\n```\n\n## Processing Instructions\n\n1. **Review each SARIF result** in the provided array\n2. **Analyze available context** (code snippets, file paths, messages)\n3. **Compare against query logic** to understand what pattern was detected\n4. **Identify TP indicators** based on guidelines above\n5. **Look for counter-evidence** (mitigations, safe patterns) that would make it an FP\n6. **Assign confidence score** reflecting evidence strength\n7. **Write clear reasoning** explaining your assessment\n8. **Sort results** by confidence score (descending)\n9. **Return top N results** as requested (or all if N not specified)\n\n## Important Notes\n\n- A result should never appear in both FP and TP rankings\n- When in doubt, prefer lower confidence scores\n- Missing code snippets should always reduce confidence\n- Production code location increases TP likelihood but is not conclusive\n- Focus on technical vulnerability evidence, not code naming conventions\n- Consider that even production code can have intentional patterns that look vulnerable but are safe\n';
+var sarif_rank_true_positives_prompt_default = '---\nagent: agent\n---\n\n# Evaluate SARIF Results for True Positives\n\n## Task\n\nAnalyze SARIF results from a CodeQL query and identify the most likely **True Positives (TPs)** - results that correctly identify real security vulnerabilities or code quality issues.\n\n## Input Context\n\nYou will be provided with:\n\n- **Query ID**: The CodeQL query/rule identifier\n- **Query Name**: Human-readable name of the query\n- **Query Content**: Full CodeQL query implementation\n- **SARIF Results**: Array of results to analyze\n- **Code Snippets**: When available, code snippets from SARIF physical locations\n\n## Recommended Tool Usage\n\nUse these tools to gather context for each result:\n\n1. **#sarif_list_rules** \u2014 Discover all rules and result counts in the SARIF data. Helps scope the analysis.\n2. **#sarif_extract_rule** \u2014 Extract results for the specific query `@id` from multi-rule SARIF. Returns a clean SARIF subset.\n3. **#sarif_rule_to_markdown** \u2014 Generate a structured markdown report with results table and Mermaid dataflow diagrams. Provides quick visual triage of dataflow paths.\n4. **#read_database_source** \u2014 Read source code from the CodeQL database using the `filePath` from the SARIF alert URI. Read 10\u201320 lines around each flagged location to verify vulnerability patterns.\n5. **#query_results_cache_lookup** with `ruleId` \u2014 Check if results for this query are already cached from previous runs.\n6. **#sarif_compare_alerts** \u2014 Compare results across different SARIF files (e.g., standard vs custom query packs) to identify which findings are unique to the query under analysis.\n7. **#sarif_diff_runs** \u2014 Compare against a baseline SARIF run to distinguish new findings from regressions.\n\n## Analysis Guidelines\n\n### What Makes a Result Likely to be a True Positive?\n\n1. **Pattern Matches**\n   - Query pattern accurately identifies the problematic code behavior\n   - Result shows clear evidence of the vulnerability or issue\n   - Code matches the exact pattern the query was designed to detect\n\n2. **Vulnerable Code Patterns**\n   - User input flows to dangerous sink without proper sanitization\n   - Missing security checks or validation\n   - Incorrect use of security-sensitive APIs\n   - Clear violation of security best practices\n\n3. **Production Code Context**\n   - File paths suggesting production code (e.g., `src/`, `lib/`, `app/`)\n   - NOT in test/example directories\n   - Function/variable names suggesting real business logic\n   - Code appears to be part of actual application functionality\n\n4. **Technical Factors**\n   - Data flow from untrusted source to dangerous operation\n   - Missing or insufficient sanitization\n   - Exploitable control flow\n   - Real security or quality implications\n\n### Important Constraints\n\n- **Be objective**: Don\'t be influenced by variable/function naming suggesting importance\n- **Require evidence**: Base conclusions on actual vulnerability patterns, not assumptions\n- **Mark uncertainty**: Use lower confidence scores when code snippets are missing\n- **Avoid false confidence**: If you cannot determine TP status, mark confidence as low\n- **Consider false positives**: Be skeptical - real vulnerabilities often have subtle mitigations\n\n### When Code Snippets Are Missing\n\nIf SARIF results lack `physicalLocation.region.snippet` or `contextRegion`:\n\n- **Lower confidence scores** (typically 0.3-0.5 instead of 0.6-0.9)\n- **Note the limitation** in reasoning\n- **Rely more on**:\n  - Result message text\n  - File path analysis\n  - Query logic understanding\n\n## Output Format\n\nReturn a JSON array of ranked results, ordered by TP likelihood (highest first):\n\n```json\n[\n  {\n    "ruleId": "query-id",\n    "message": { "text": "original result message" },\n    "locations": [...],\n    "confidence": 0.85,\n    "reasoning": "This appears to be a true positive because: (1) the file path \'src/api/user-controller.js\' indicates production code, (2) user input from request parameter flows directly to SQL query without sanitization, (3) no validation or prepared statement usage detected.",\n    "sourceFile": "results-1.sarif",\n    "resultIndex": 15\n  }\n]\n```\n\n### Confidence Score Guidelines\n\n- **0.8-1.0**: Strong evidence of TP (e.g., clear vulnerability with exploit path)\n- **0.6-0.8**: Good evidence of TP (e.g., production code with problematic pattern)\n- **0.4-0.6**: Moderate evidence of TP (e.g., pattern matches but context unclear)\n- **0.2-0.4**: Weak evidence of TP (e.g., possible issue but missing context)\n- **0.0-0.2**: Minimal evidence (uncertain, need more information)\n\n## Examples\n\n### High-Confidence TP Example\n\n```json\n{\n  "ruleId": "js/sql-injection",\n  "message": { "text": "Unsanitized user input in SQL query" },\n  "confidence": 0.9,\n  "reasoning": "True positive: (1) File path \'src/controllers/UserController.js\' indicates production code, (2) User input from req.query.userId flows directly to SQL query string concatenation, (3) No prepared statements or sanitization visible in code snippet, (4) Classic SQL injection pattern. Confidence is 0.9 not 1.0 due to possibility of sanitization elsewhere in call chain."\n}\n```\n\n### Moderate-Confidence TP Example\n\n```json\n{\n  "ruleId": "js/path-injection",\n  "message": { "text": "Potential path traversal vulnerability" },\n  "confidence": 0.6,\n  "reasoning": "Likely true positive: (1) File path \'src/utils/fileHandler.js\' suggests production utility code, (2) User-controlled filename parameter used in fs.readFile(), (3) No visible path validation, but code snippet is limited. Moderate confidence due to incomplete context - may have validation in calling code."\n}\n```\n\n### Low-Confidence TP Example (Missing Snippets)\n\n```json\n{\n  "ruleId": "java/unsafe-deserialization",\n  "message": { "text": "Unsafe deserialization of user data" },\n  "confidence": 0.4,\n  "reasoning": "Possibly a true positive: (1) File path \'src/main/java/com/app/handlers/DataHandler.java\' indicates production code, (2) Message suggests unsafe deserialization pattern, (3) No code snippets available in SARIF to verify actual vulnerability or confirm absence of mitigations. Confidence is low due to missing context."\n}\n```\n\n## Processing Instructions\n\n1. **Review each SARIF result** in the provided array\n2. **Analyze available context** (code snippets, file paths, messages)\n3. **Compare against query logic** to understand what pattern was detected\n4. **Identify TP indicators** based on guidelines above\n5. **Look for counter-evidence** (mitigations, safe patterns) that would make it an FP\n6. **Assign confidence score** reflecting evidence strength\n7. **Write clear reasoning** explaining your assessment\n8. **Sort results** by confidence score (descending)\n9. **Return top N results** as requested (or all if N not specified)\n\n## Important Notes\n\n- A result should never appear in both FP and TP rankings\n- When in doubt, prefer lower confidence scores\n- Missing code snippets should always reduce confidence\n- Production code location increases TP likelihood but is not conclusive\n- Focus on technical vulnerability evidence, not code naming conventions\n- Consider that even production code can have intentional patterns that look vulnerable but are safe\n';
 
 // src/prompts/tools-query-workflow.prompt.md
 var tools_query_workflow_prompt_default = '---\nagent: agent\n---\n\n# Using CodeQL Development MCP Server Tools Queries\n\nThis guide helps you use the built-in "tools" queries (`PrintAST`, `PrintCFG`, `CallGraphFrom`, `CallGraphTo`) that ship with the CodeQL Development MCP Server to understand code structure before writing detection queries.\n\n## Why Use Tools Queries?\n\nTools queries provide essential insights into how CodeQL represents your source code:\n\n| Query           | Purpose                                          | Use When                                        |\n| --------------- | ------------------------------------------------ | ----------------------------------------------- |\n| `PrintAST`      | Visualize the Abstract Syntax Tree               | Understanding code structure, finding AST nodes |\n| `PrintCFG`      | Visualize Control Flow Graphs                    | Understanding execution paths, loop/branch flow |\n| `CallGraphFrom` | Find all functions called by a specific function | Tracing data flow through call chains           |\n| `CallGraphTo`   | Find all functions that call a specific function | Understanding function usage patterns           |\n\n## Supported Languages\n\nTools queries are available for: `actions`, `cpp`, `csharp`, `go`, `java`, `javascript`, `python`, `ruby`, `rust`, `swift`\n\n## Prerequisites\n\nBefore using tools queries, you need:\n\n1. **A CodeQL database** - Either create one or use an existing database\n2. **Source files to analyze** - The tools queries filter output to specific files\n\n## Workflow Checklist\n\n### Step 1: Identify or Create Database\n\n- [ ] **Option A: Use existing database**\n  - Tool: #codeql_resolve_database\n  - Verify database is valid and note the language\n\n- [ ] **Option B: Create new database**\n  - Tool: #codeql_database_create\n  - Parameters: `database`, `language`, `source-root`\n\n### Step 2: Run PrintAST Query\n\nThe PrintAST query outputs a hierarchical tree of AST nodes with labels.\n\n- [ ] **Execute PrintAST**\n  - Tool: #codeql_query_run\n  - Parameters:\n    - `database`: Path to your CodeQL database\n    - `queryName`: `"PrintAST"`\n    - `queryLanguage`: Your language (e.g., `"javascript"`, `"python"`, `"cpp"`)\n    - `sourceFiles`: Comma-separated file names to analyze (e.g., `"main.js,utils.js"`)\n    - `format`: `"graphtext"` (for human-readable output)\n\n- [ ] **Verify output contains AST nodes**\n  - Look for hierarchical structure with indentation\n  - Confirm nodes have `semmle.label` with class names\n  - Identify relevant AST classes for your query\n\n**Example AST output structure:**\n\n```text\nTopLevelFunction\n\u251C\u2500\u2500 FunctionDeclarationEntry\n\u251C\u2500\u2500 Block\n\u2502   \u251C\u2500\u2500 DeclStmt\n\u2502   \u2502   \u2514\u2500\u2500 LocalVariable\n\u2502   \u251C\u2500\u2500 ExprStmt\n\u2502   \u2502   \u2514\u2500\u2500 FunctionCall\n\u2502   \u2514\u2500\u2500 ReturnStmt\n```\n\n### Step 3: Run PrintCFG Query (if needed)\n\nThe PrintCFG query outputs control flow nodes and edges.\n\n- [ ] **Execute PrintCFG**\n  - Tool: #codeql_query_run\n  - Parameters:\n    - `database`: Path to your CodeQL database\n    - `queryName`: `"PrintCFG"`\n    - `queryLanguage`: Your language\n    - `sourceFunction`: Function name to analyze (e.g., `"processData"`)\n    - `format`: `"graphtext"`\n\n- [ ] **Verify output contains nodes and edges**\n  - Look for `nodes` section with CFG nodes\n  - Look for `edges` section with `\u2192` arrows showing flow\n  - Identify control flow patterns (loops, branches)\n\n**Example CFG output structure:**\n\n```text\nnodes\n| node | semmle.label |\n| ... | entry: processData |\n| ... | if (...) |\n| ... | return |\n\nedges\n| from | to | semmle.label |\n| ... | ... | \u2192 |\n```\n\n### Step 4: Run CallGraph Queries (if needed)\n\nCall graph queries help trace function relationships.\n\n- [ ] **Execute CallGraphFrom** (to find what a function calls)\n  - Tool: #codeql_query_run\n  - Parameters:\n    - `database`: Path to your CodeQL database\n    - `queryName`: `"CallGraphFrom"`\n    - `queryLanguage`: Your language\n    - `sourceFunction`: Function name to trace from (e.g., `"main"`)\n    - `format`: `"sarif-latest"` or `"csv"`\n\n- [ ] **Execute CallGraphTo** (to find what calls a function)\n  - Tool: #codeql_query_run\n  - Parameters:\n    - `database`: Path to your CodeQL database\n    - `queryName`: `"CallGraphTo"`\n    - `queryLanguage`: Your language\n    - `targetFunction`: Function name to find callers of (e.g., `"validate"`)\n    - `format`: `"sarif-latest"` or `"csv"`\n\n- [ ] **Verify call relationships**\n  - Confirm results show caller \u2192 callee relationships\n  - Note function locations for further analysis\n\n### Step 5: Apply Insights to Query Development\n\nUse the gathered information to inform your query:\n\n- [ ] **From PrintAST**: Identify which AST classes to use in your `from` clause\n- [ ] **From PrintCFG**: Understand execution paths for control-flow-sensitive queries\n- [ ] **From CallGraph**: Map data flow paths through function boundaries\n\n## Common Patterns\n\n### Pattern 1: Finding All Function Calls\n\n```text\n1. Run PrintAST on your source file\n2. Look for FunctionCall, MethodAccess, or similar nodes\n3. Note the parent/child relationships\n4. Use those AST classes in your query\n```\n\n### Pattern 2: Tracing Data Through Functions\n\n```text\n1. Run CallGraphFrom on your entry point function\n2. Identify which functions are called\n3. Run CallGraphTo on sink functions\n4. Map the complete path from source to sink\n```\n\n### Pattern 3: Understanding Loop Structures\n\n```text\n1. Run PrintAST to find loop constructs (ForStmt, WhileStmt, etc.)\n2. Run PrintCFG on the containing function\n3. Identify back edges that represent loop iteration\n4. Use CFG analysis for loop-sensitive queries\n```\n\n## Troubleshooting\n\n| Issue                 | Likely Cause                          | Resolution                                             |\n| --------------------- | ------------------------------------- | ------------------------------------------------------ |\n| Empty AST output      | `sourceFiles` parameter not matching  | Use just filenames, not full paths (e.g., `"test.js"`) |\n| Empty CFG output      | `sourceFunction` not found            | Check exact function name spelling                     |\n| Empty CallGraph       | No calls exist or wrong function name | Verify function exists and has calls                   |\n| Query compilation err | Pack dependencies missing             | Run #codeql_pack_install on the tools pack             |\n\n## MCP Tools Reference\n\n| Tool                     | Purpose                                              |\n| ------------------------ | ---------------------------------------------------- |\n| #codeql_query_run        | Execute tools queries with parameters                |\n| #codeql_resolve_database | Validate database before querying                    |\n| #codeql_database_create  | Create database from source code                     |\n| #codeql_bqrs_interpret   | Convert results to different formats                 |\n| #codeql_pack_install     | Install pack dependencies if needed                  |\n| #codeql_lsp_completion   | Explore available types after seeing AST class names |\n| #codeql_lsp_definition   | Navigate to class definitions to see predicates      |\n| #codeql_lsp_references   | Find usage examples of a class or predicate          |\n| #search_ql_code          | Search QL source files for patterns (text or regex)  |\n| #codeql_resolve_files    | Find QL files by name, extension, or glob pattern    |\n\n### Using LSP Tools After AST Analysis\n\nAfter running PrintAST and identifying relevant AST class names, use the LSP tools\nto explore those classes in your query file:\n\n1. **Write the class name** in your query\'s `from` clause and save the file\n2. **Run #codeql_lsp_completion** after the dot to see member predicates:\n   - `file_path`: your query file, `line`/`character`: 0-based position after the dot\n   - `workspace_uri`: the pack root directory (containing `codeql-pack.yml`)\n3. **Run #codeql_lsp_definition** on an AST class name to see its full API\n4. **Run #codeql_lsp_references** to find usage examples in the pack\n\n> **Note**: LSP tools use 0-based line/character positions. Run #codeql_pack_install\n> before using them \u2014 they require resolved dependencies. Set `workspace_uri` to\n> a plain directory path (not a `file://` URI).\n\nFor the full iterative LSP development workflow, see: `codeql://prompts/ql_lsp_iterative_development`\n';
@@ -191746,6 +192458,7 @@ var workshop_creation_workflow_prompt_default = '---\nagent: agent\n---\n\n# Cre
 // src/prompts/prompt-loader.ts
 var PROMPT_TEMPLATES = {
   "check-for-duplicated-code.prompt.md": check_for_duplicated_code_prompt_default,
+  "compare-overlapping-alerts.prompt.md": compare_overlapping_alerts_prompt_default,
   "document-codeql-query.prompt.md": document_codeql_query_prompt_default,
   "explain-codeql-query.prompt.md": explain_codeql_query_prompt_default,
   "find-overlapping-queries.prompt.md": find_overlapping_queries_prompt_default,
@@ -191916,6 +192629,13 @@ var checkForDuplicatedCodeSchema = external_exports.object({
   queryPath: external_exports.string().describe("Path to the .ql or .qll file to audit for duplicated definitions"),
   workspaceUri: external_exports.string().optional().describe("Pack root directory containing codeql-pack.yml (for LSP resolution)")
 });
+var compareOverlappingAlertsSchema = external_exports.object({
+  databasePath: external_exports.string().optional().describe("Path to the CodeQL database for reading source code context"),
+  ruleIdA: external_exports.string().optional().describe('First CodeQL query @id / SARIF rule ID (e.g. "js/sql-injection"). Omit to compare all rules.'),
+  ruleIdB: external_exports.string().optional().describe('Second CodeQL query @id / SARIF rule ID (e.g. "js/cap-sql-injection"). Omit to compare all rules.'),
+  sarifPathA: external_exports.string().describe("Path to the first SARIF file (or the only file when comparing within one file)"),
+  sarifPathB: external_exports.string().optional().describe("Path to the second SARIF file (for cross-run or cross-database comparison)")
+});
 var findOverlappingQueriesSchema = external_exports.object({
   queryDescription: external_exports.string().describe(
     `Description of the new query's purpose and target constructs (e.g. "detect placement-new on types with non-trivial destructors")`
@@ -192011,6 +192731,7 @@ Please check your inputs and try again.`
 }
 var WORKFLOW_PROMPT_NAMES = [
   "check_for_duplicated_code",
+  "compare_overlapping_alerts",
   "document_codeql_query",
   "explain_codeql_query",
   "find_overlapping_queries",
@@ -192493,6 +193214,56 @@ ${workspaceUri ? `- **Workspace URI**: ${workspaceUri}
       }
     )
   );
+  server.prompt(
+    "compare_overlapping_alerts",
+    "Compare CodeQL SARIF alerts across rules, files, runs, databases, or CodeQL versions. Detect overlap, redundancy, and behavioral deviations.",
+    toPermissiveShape(compareOverlappingAlertsSchema.shape),
+    createSafePromptHandler(
+      "compare_overlapping_alerts",
+      compareOverlappingAlertsSchema,
+      async ({ sarifPathA, sarifPathB, ruleIdA, ruleIdB, databasePath }) => {
+        const template = loadPromptTemplate("compare-overlapping-alerts.prompt.md");
+        const content = processPromptTemplate(template, {
+          sarifPathA,
+          sarifPathB: sarifPathB || sarifPathA,
+          ruleIdA: ruleIdA || "<all-rules>",
+          ruleIdB: ruleIdB || "<all-rules>",
+          databasePath: databasePath || "<database-path>"
+        });
+        let contextSection = "## Alert Comparison Context\n\n";
+        contextSection += `- **SARIF Path A**: ${sarifPathA}
+`;
+        if (sarifPathB) {
+          contextSection += `- **SARIF Path B**: ${sarifPathB}
+`;
+        }
+        if (ruleIdA) {
+          contextSection += `- **Rule A**: ${ruleIdA}
+`;
+        }
+        if (ruleIdB) {
+          contextSection += `- **Rule B**: ${ruleIdB}
+`;
+        }
+        if (databasePath) {
+          contextSection += `- **Database Path**: ${databasePath}
+`;
+        }
+        contextSection += "\n";
+        return {
+          messages: [
+            {
+              role: "user",
+              content: {
+                type: "text",
+                text: contextSection + content
+              }
+            }
+          ]
+        };
+      }
+    )
+  );
   logger.info(`Registered ${WORKFLOW_PROMPT_NAMES.length} workflow prompts`);
 }
 function buildToolsQueryContext(language, database, sourceFiles, sourceFunction, targetFunction) {
@@ -193667,16 +194438,35 @@ function registerAuditListFindingsTool(server) {
 function registerAuditAddNotesTool(server) {
   server.tool(
     "audit_add_notes",
-    "Append notes to an existing audit finding. The notes are appended to the annotation content.",
+    "Append notes to an existing audit finding. Identify the finding by findingId (preferred) or by owner+repo+sourceLocation+line.",
     {
-      owner: external_exports.string().describe("Repository owner."),
-      repo: external_exports.string().describe("Repository name."),
-      sourceLocation: external_exports.string().describe("File path of the finding."),
-      line: external_exports.number().int().min(1).describe("Line number of the finding (integer >= 1)."),
+      findingId: external_exports.number().int().positive().optional().describe("Annotation ID of the finding (returned by audit_store_findings and audit_list_findings). Preferred lookup method."),
+      owner: external_exports.string().optional().describe("Repository owner (required when findingId is not provided)."),
+      repo: external_exports.string().optional().describe("Repository name (required when findingId is not provided)."),
+      sourceLocation: external_exports.string().optional().describe("File path of the finding (required when findingId is not provided)."),
+      line: external_exports.number().int().min(1).optional().describe("Line number of the finding (required when findingId is not provided)."),
       notes: external_exports.string().describe("Notes to append.")
     },
-    async ({ owner, repo, sourceLocation, line, notes }) => {
+    async ({ findingId, owner, repo, sourceLocation, line, notes }) => {
       const store = sessionDataManager.getStore();
+      if (findingId != null) {
+        const annotation2 = store.getAnnotation(findingId);
+        if (!annotation2 || annotation2.category !== AUDIT_CATEGORY) {
+          return {
+            content: [{ type: "text", text: `No audit finding found with id ${findingId}.` }]
+          };
+        }
+        const updatedContent2 = (annotation2.content || "") + "\n" + notes;
+        store.updateAnnotation(annotation2.id, { content: updatedContent2.trim() });
+        return {
+          content: [{ type: "text", text: `Updated notes for finding id ${findingId}.` }]
+        };
+      }
+      if (!owner || !repo || !sourceLocation || !line) {
+        return {
+          content: [{ type: "text", text: "Either findingId or all of owner+repo+sourceLocation+line must be provided." }]
+        };
+      }
       const entityKey = `${repoKey(owner, repo)}:${sourceLocation}:L${line}`;
       const existing = store.listAnnotations({
         category: AUDIT_CATEGORY,
@@ -193742,11 +194532,12 @@ function registerQueryResultsCacheLookupTool(server) {
     {
       cacheKey: external_exports.string().optional().describe("Look up by exact cache key (if known)."),
       queryName: external_exports.string().optional().describe('Query name to search for (e.g. "PrintAST", "CallGraphFrom").'),
+      ruleId: external_exports.string().optional().describe('Filter by CodeQL query @id (e.g. "js/sql-injection"). The @id is the most reliable identifier.'),
       databasePath: external_exports.string().optional().describe("Database path to search for."),
       language: external_exports.string().optional().describe('Filter by language (e.g. "cpp", "javascript").'),
       limit: external_exports.number().int().positive().max(500).optional().describe("Maximum number of cache entries to return when listing by filter (default: 50, max: 500).")
     },
-    async ({ cacheKey: cacheKey2, queryName, databasePath, language, limit }) => {
+    async ({ cacheKey: cacheKey2, queryName, ruleId, databasePath, language, limit }) => {
       const store = sessionDataManager.getStore();
       if (cacheKey2) {
         const meta = store.getCacheEntryMeta(cacheKey2);
@@ -193755,9 +194546,9 @@ function registerQueryResultsCacheLookupTool(server) {
         }
         return { content: [{ type: "text", text: JSON.stringify({ cached: false, cacheKey: cacheKey2 }) }] };
       }
-      const entries = store.listCacheEntries({ queryName, databasePath, language, limit: limit ?? 50 });
+      const entries = store.listCacheEntries({ queryName, ruleId, databasePath, language, limit: limit ?? 50 });
       if (entries.length === 0) {
-        return { content: [{ type: "text", text: JSON.stringify({ cached: false, queryName, databasePath, language }) }] };
+        return { content: [{ type: "text", text: JSON.stringify({ cached: false, queryName, ruleId, databasePath, language }) }] };
       }
       return {
         content: [{
@@ -193846,15 +194637,16 @@ function registerQueryResultsCacheClearTool(server) {
     {
       cacheKey: external_exports.string().optional().describe("Clear a specific cache entry."),
       queryName: external_exports.string().optional().describe("Clear all entries for this query name."),
+      ruleId: external_exports.string().optional().describe("Clear all entries for this CodeQL query @id."),
       databasePath: external_exports.string().optional().describe("Clear all entries for this database."),
       all: external_exports.boolean().optional().describe("Clear the entire query results cache.")
     },
-    async ({ cacheKey: cacheKey2, queryName, databasePath, all }) => {
-      if (!cacheKey2 && !queryName && !databasePath && !all) {
-        return { content: [{ type: "text", text: "At least one filter (cacheKey, queryName, databasePath, or all) is required." }] };
+    async ({ cacheKey: cacheKey2, queryName, ruleId, databasePath, all }) => {
+      if (!cacheKey2 && !queryName && !ruleId && !databasePath && !all) {
+        return { content: [{ type: "text", text: "At least one filter (cacheKey, queryName, ruleId, databasePath, or all) is required." }] };
       }
       const store = sessionDataManager.getStore();
-      const cleared = store.clearCacheEntries({ cacheKey: cacheKey2, queryName, databasePath, all: all ?? false });
+      const cleared = store.clearCacheEntries({ cacheKey: cacheKey2, queryName, ruleId, databasePath, all: all ?? false });
       return { content: [{ type: "text", text: `Cleared ${cleared} cached query result(s).` }] };
     }
   );
@@ -193864,14 +194656,19 @@ function registerQueryResultsCacheCompareTool(server) {
     "query_results_cache_compare",
     "Compare cached query results across multiple databases for the same query. Useful for MRVA-style cross-repository analysis.",
     {
-      queryName: external_exports.string().describe("The query name to compare across databases."),
+      queryName: external_exports.string().optional().describe("The query name to compare across databases."),
+      ruleId: external_exports.string().optional().describe("The CodeQL query @id to compare across databases (preferred over queryName)."),
       language: external_exports.string().optional().describe("Filter by language.")
     },
-    async ({ queryName, language }) => {
+    async ({ queryName, ruleId, language }) => {
+      if (!queryName && !ruleId) {
+        return { content: [{ type: "text", text: "Either queryName or ruleId is required." }] };
+      }
       const store = sessionDataManager.getStore();
-      const entries = store.listCacheEntries({ queryName, language });
+      const entries = store.listCacheEntries({ queryName, ruleId, language });
       if (entries.length === 0) {
-        return { content: [{ type: "text", text: `No cached results found for query "${queryName}".` }] };
+        const identifier = ruleId ?? queryName;
+        return { content: [{ type: "text", text: `No cached results found for "${identifier}".` }] };
       }
       const byDatabase = /* @__PURE__ */ new Map();
       for (const entry of entries) {
@@ -193879,19 +194676,25 @@ function registerQueryResultsCacheCompareTool(server) {
         if (!byDatabase.has(key)) byDatabase.set(key, []);
         byDatabase.get(key).push(entry);
       }
-      const comparison = Array.from(byDatabase.entries()).map(([db, dbEntries]) => ({
-        database: db,
-        languages: [...new Set(dbEntries.map((e) => e.language))],
-        formats: [...new Set(dbEntries.map((e) => e.outputFormat))],
-        totalResultCount: dbEntries.reduce((sum, e) => sum + (e.resultCount ?? 0), 0),
-        cachedRuns: dbEntries.length,
-        latestCachedAt: dbEntries[0].createdAt
-      }));
+      const comparison = Array.from(byDatabase.entries()).map(([db, dbEntries]) => {
+        const latestEntry = dbEntries[0];
+        const resultCount = latestEntry.resultCount ?? 0;
+        return {
+          database: db,
+          languages: [...new Set(dbEntries.map((e) => e.language))],
+          formats: [...new Set(dbEntries.map((e) => e.outputFormat))],
+          resultCount,
+          totalResultCount: resultCount,
+          cachedRuns: dbEntries.length,
+          latestCachedAt: dbEntries[0].createdAt
+        };
+      });
       return {
         content: [{
           type: "text",
           text: JSON.stringify({
-            queryName,
+            queryName: queryName ?? null,
+            ruleId: ruleId ?? null,
             databases: comparison.length,
             comparison
           }, null, 2)
@@ -193901,6 +194704,264 @@ function registerQueryResultsCacheCompareTool(server) {
   );
 }
 
+// src/tools/sarif-tools.ts
+import { readFileSync as readFileSync13 } from "fs";
+init_logger();
+function registerSarifTools(server) {
+  const config2 = sessionDataManager.getConfig();
+  if (!config2.enableAnnotationTools) {
+    logger.info(
+      "SARIF tools are disabled (opt-in). Set ENABLE_ANNOTATION_TOOLS=true to enable sarif_* tools."
+    );
+    return;
+  }
+  registerSarifExtractRuleTool(server);
+  registerSarifListRulesTool(server);
+  registerSarifRuleToMarkdownTool(server);
+  registerSarifCompareAlertsTool(server);
+  registerSarifDiffRunsTool(server);
+  logger.info("Registered SARIF analysis tools");
+}
+function loadSarif(sarifPath, cacheKey2) {
+  if (!sarifPath && !cacheKey2) {
+    return { error: "Either sarifPath or cacheKey is required." };
+  }
+  let content;
+  if (cacheKey2) {
+    const store = sessionDataManager.getStore();
+    const cached2 = store.getCacheContent(cacheKey2);
+    if (!cached2) {
+      return { error: `No cached content found for key: ${cacheKey2}` };
+    }
+    content = cached2;
+  } else {
+    try {
+      content = readFileSync13(sarifPath, "utf8");
+    } catch {
+      return { error: `Failed to read SARIF file: ${sarifPath}` };
+    }
+  }
+  try {
+    const parsed = JSON.parse(content);
+    if (!parsed || typeof parsed !== "object") {
+      return { error: "Invalid SARIF: expected a JSON object." };
+    }
+    if (!Array.isArray(parsed.runs)) {
+      return { error: 'Invalid SARIF: missing or invalid "runs" array.' };
+    }
+    if (parsed.runs.length === 0) {
+      return { error: 'Invalid SARIF: "runs" array is empty.' };
+    }
+    const run = parsed.runs[0];
+    if (!run.tool?.driver) {
+      return { error: "Invalid SARIF: missing tool.driver in first run." };
+    }
+    return { sarif: parsed };
+  } catch {
+    return { error: "Failed to parse SARIF JSON." };
+  }
+}
+function registerSarifExtractRuleTool(server) {
+  server.tool(
+    "sarif_extract_rule",
+    "Extract all data for a specific rule/query from multi-rule SARIF. Returns a valid SARIF JSON subset with only the matching rule definition and results.",
+    {
+      cacheKey: external_exports.string().optional().describe("Cache key to read SARIF from (alternative to sarifPath)."),
+      ruleId: external_exports.string().describe('The SARIF rule ID to extract (e.g. "js/sql-injection"). Corresponds to the CodeQL query @id.'),
+      sarifPath: external_exports.string().optional().describe("Path to the SARIF file.")
+    },
+    async ({ sarifPath, cacheKey: cacheKey2, ruleId }) => {
+      const loaded = loadSarif(sarifPath, cacheKey2);
+      if (loaded.error) {
+        return { content: [{ type: "text", text: loaded.error }] };
+      }
+      const extracted = extractRuleFromSarif(loaded.sarif, ruleId);
+      const resultCount = extracted.runs[0]?.results?.length ?? 0;
+      const ruleCount = extracted.runs[0]?.tool.driver.rules?.length ?? 0;
+      if (resultCount === 0 && ruleCount === 0) {
+        return {
+          content: [{
+            type: "text",
+            text: `No results or rule definition found for ruleId "${ruleId}" in the SARIF data.`
+          }]
+        };
+      }
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            ruleId,
+            resultCount,
+            extractedSarif: extracted
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+function registerSarifListRulesTool(server) {
+  server.tool(
+    "sarif_list_rules",
+    "List all rules in a SARIF file with result counts, severity, precision, and tags. Essential for discovering available rules before extraction or comparison.",
+    {
+      cacheKey: external_exports.string().optional().describe("Cache key to read SARIF from (alternative to sarifPath)."),
+      sarifPath: external_exports.string().optional().describe("Path to the SARIF file.")
+    },
+    async ({ sarifPath, cacheKey: cacheKey2 }) => {
+      const loaded = loadSarif(sarifPath, cacheKey2);
+      if (loaded.error) {
+        return { content: [{ type: "text", text: loaded.error }] };
+      }
+      const rules = listSarifRules(loaded.sarif);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            totalRules: rules.length,
+            totalResults: rules.reduce((sum, r) => sum + r.resultCount, 0),
+            rules
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+function registerSarifRuleToMarkdownTool(server) {
+  server.tool(
+    "sarif_rule_to_markdown",
+    "Convert per-rule SARIF data to a structured markdown report with Mermaid dataflow diagrams. Renders dataflow paths as visual flowcharts.",
+    {
+      cacheKey: external_exports.string().optional().describe("Cache key to read SARIF from (alternative to sarifPath)."),
+      ruleId: external_exports.string().describe('The rule ID to render (e.g. "js/sql-injection").'),
+      sarifPath: external_exports.string().optional().describe("Path to the SARIF file.")
+    },
+    async ({ sarifPath, cacheKey: cacheKey2, ruleId }) => {
+      const loaded = loadSarif(sarifPath, cacheKey2);
+      if (loaded.error) {
+        return { content: [{ type: "text", text: loaded.error }] };
+      }
+      const markdown = sarifRuleToMarkdown(loaded.sarif, ruleId);
+      if (!markdown) {
+        return {
+          content: [{
+            type: "text",
+            text: `No results found for ruleId "${ruleId}" in the SARIF data.`
+          }]
+        };
+      }
+      return {
+        content: [{
+          type: "text",
+          text: markdown
+        }]
+      };
+    }
+  );
+}
+function registerSarifCompareAlertsTool(server) {
+  const alertSpecSchema = external_exports.object({
+    cacheKey: external_exports.string().optional().describe("Cache key for the SARIF data."),
+    resultIndex: external_exports.number().int().min(0).describe("0-based index of the result within the rule's results."),
+    ruleId: external_exports.string().describe("The rule ID of the alert."),
+    sarifPath: external_exports.string().optional().describe("Path to the SARIF file.")
+  });
+  server.tool(
+    "sarif_compare_alerts",
+    "Compare code locations of two SARIF alerts to detect overlap. Supports sink, source, any-location, and full-path comparison modes.",
+    {
+      alertA: alertSpecSchema.describe("First alert to compare."),
+      alertB: alertSpecSchema.describe("Second alert to compare."),
+      overlapMode: external_exports.enum(["sink", "source", "any-location", "full-path"]).optional().default("sink").describe('Comparison mode: "sink" (primary locations), "source" (first dataflow step), "any-location" (all locations), "full-path" (structural path similarity).')
+    },
+    async ({ alertA, alertB, overlapMode }) => {
+      const loadedA = loadSarif(alertA.sarifPath, alertA.cacheKey);
+      if (loadedA.error) {
+        return { content: [{ type: "text", text: `Alert A: ${loadedA.error}` }] };
+      }
+      const loadedB = loadSarif(alertB.sarifPath, alertB.cacheKey);
+      if (loadedB.error) {
+        return { content: [{ type: "text", text: `Alert B: ${loadedB.error}` }] };
+      }
+      const extractedA = extractRuleFromSarif(loadedA.sarif, alertA.ruleId);
+      const resultsA = extractedA.runs[0]?.results ?? [];
+      if (alertA.resultIndex >= resultsA.length) {
+        return { content: [{ type: "text", text: `Alert A: resultIndex ${alertA.resultIndex} out of range (${resultsA.length} results for rule "${alertA.ruleId}").` }] };
+      }
+      const extractedB = extractRuleFromSarif(loadedB.sarif, alertB.ruleId);
+      const resultsB = extractedB.runs[0]?.results ?? [];
+      if (alertB.resultIndex >= resultsB.length) {
+        return { content: [{ type: "text", text: `Alert B: resultIndex ${alertB.resultIndex} out of range (${resultsB.length} results for rule "${alertB.ruleId}").` }] };
+      }
+      const resultA = resultsA[alertA.resultIndex];
+      const resultB = resultsB[alertB.resultIndex];
+      const overlap = computeLocationOverlap(resultA, resultB, overlapMode);
+      const locA = resultA.locations?.[0]?.physicalLocation;
+      const locB = resultB.locations?.[0]?.physicalLocation;
+      const locStrA = locA ? `${locA.artifactLocation?.uri ?? "?"}:${locA.region?.startLine ?? "?"}` : "?";
+      const locStrB = locB ? `${locB.artifactLocation?.uri ?? "?"}:${locB.region?.startLine ?? "?"}` : "?";
+      const response = {
+        overlaps: overlap.overlaps,
+        overlapMode: overlap.overlapMode,
+        alertA: {
+          ruleId: alertA.ruleId,
+          location: locStrA,
+          message: resultA.message.text
+        },
+        alertB: {
+          ruleId: alertB.ruleId,
+          location: locStrB,
+          message: resultB.message.text
+        },
+        sharedLocations: overlap.sharedLocations
+      };
+      if (overlap.pathSimilarity !== void 0) {
+        response.pathSimilarity = overlap.pathSimilarity;
+      }
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify(response, null, 2)
+        }]
+      };
+    }
+  );
+}
+function registerSarifDiffRunsTool(server) {
+  server.tool(
+    "sarif_diff_runs",
+    "Diff two SARIF files or cached results to find added, removed, and changed rules/results. Useful for comparing analysis across CodeQL versions, database updates, or query pack releases.",
+    {
+      cacheKeyA: external_exports.string().optional().describe("Cache key for the first (baseline) SARIF."),
+      cacheKeyB: external_exports.string().optional().describe("Cache key for the second (comparison) SARIF."),
+      labelA: external_exports.string().optional().describe('Label for the first run (e.g. "v2.20.3", "main-branch", "database-A").'),
+      labelB: external_exports.string().optional().describe('Label for the second run (e.g. "v2.20.4", "feature-branch", "database-B").'),
+      sarifPathA: external_exports.string().optional().describe("Path to the first (baseline) SARIF file."),
+      sarifPathB: external_exports.string().optional().describe("Path to the second (comparison) SARIF file.")
+    },
+    async ({ sarifPathA, sarifPathB, cacheKeyA, cacheKeyB, labelA, labelB }) => {
+      const loadedA = loadSarif(sarifPathA, cacheKeyA);
+      if (loadedA.error) {
+        return { content: [{ type: "text", text: `Run A: ${loadedA.error}` }] };
+      }
+      const loadedB = loadSarif(sarifPathB, cacheKeyB);
+      if (loadedB.error) {
+        return { content: [{ type: "text", text: `Run B: ${loadedB.error}` }] };
+      }
+      const diff = diffSarifRules(loadedA.sarif, loadedB.sarif);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            labelA: labelA ?? "Run A",
+            labelB: labelB ?? "Run B",
+            ...diff
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+
 // src/codeql-development-mcp-server.ts
 init_cli_executor();
 init_server_manager();
@@ -193908,7 +194969,7 @@ init_package_paths();
 init_logger();
 import_dotenv.default.config({ path: resolve14(packageRootDir, ".env"), quiet: true });
 var PACKAGE_NAME = "codeql-development-mcp-server";
-var VERSION = "2.25.1-next.1";
+var VERSION = "2.25.1-next.2";
 async function startServer(mode = "stdio") {
   logger.info(`Starting CodeQL Development MCP McpServer v${VERSION} in ${mode} mode`);
   const codeqlBinary = resolveCodeQLBinary();
@@ -193928,6 +194989,7 @@ async function startServer(mode = "stdio") {
   registerAnnotationTools(server);
   registerAuditTools(server);
   registerCacheTools(server);
+  registerSarifTools(server);
   await sessionDataManager.initialize();
   const manager = initServerManager();
   Promise.all([
@@ -194005,7 +195067,7 @@ async function main() {
     process.exit(1);
   }
 }
-var scriptPath = process.argv[1] ? realpathSync2(resolve14(process.argv[1])) : void 0;
+var scriptPath = process.argv[1] ? realpathSync3(resolve14(process.argv[1])) : void 0;
 if (scriptPath && import.meta.url === pathToFileURL5(scriptPath).href) {
   main();
 }