@krotovm/gitlab-ai-review 1.0.26 → 1.0.27

package/README.md

@@ -30,6 +30,24 @@ ai_review:
     - npx -y @krotovm/gitlab-ai-review
 ```
 
+Save debug HTML as a CI artifact:
+
+```yaml
+stages: [review]
+
+ai_review:
+  stage: review
+  image: node:20
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+  script:
+    - npx -y @krotovm/gitlab-ai-review --include-artifacts
+  artifacts:
+    expire_in: 7 days
+    paths:
+      - ai-review-report.html
+```
+
 ## Env variables
 
 Set these in your project/group CI settings:
@@ -39,7 +57,7 @@ Set these in your project/group CI settings:
 - `AI_MODEL` (optional, default: `gpt-4o-mini`; example: `gpt-4o`)
 - `PROJECT_ACCESS_TOKEN` (optional for public projects, but required for most private projects; token with `api` scope)
 - `GITLAB_TOKEN` (optional alias for `PROJECT_ACCESS_TOKEN`)
-- `AI_REVIEW_ARTIFACT_HTML_FILE` (optional, default: `.ai-review-debug.html`; used with `--include-artifacts`)
+- `AI_REVIEW_ARTIFACT_HTML_FILE` (optional, default: `ai-review-report.html`; used with `--include-artifacts`)
 
 `OPENAI_BASE_URL` is passed through to the `openai` SDK client, so you can use any OpenAI-compatible gateway/provider endpoint.
 

package/dist/cli/ci-review.js

@@ -2,7 +2,7 @@
 import OpenAI from "openai";
 import { buildAnswer, buildConsolidatePrompt, buildFileReviewPrompt, buildPrompt, buildTriagePrompt, buildVerificationPrompt, extractCompletionText, parseTriageResponse, } from "../prompt/index.js";
 import { fetchFileAtRef, searchRepository, } from "../gitlab/services.js";
-import { logToolUsageMinimal, MAX_FILE_TOOL_ROUNDS, MAX_TOOL_ROUNDS, TOOL_NAME_GET_FILE, TOOL_NAME_GREP, } from "./tooling.js";
+import { logToolUsageMinimal, MAX_FILE_TOOL_ROUNDS, MAX_TOOL_ROUNDS, MAX_VERIFICATION_TOOL_ROUNDS, TOOL_NAME_GET_FILE, TOOL_NAME_GREP, } from "./tooling.js";
 async function appendDebugDump(_debugDumpFile, debugRecordWriter, record) {
     const withTs = { ts: new Date().toISOString(), ...record };
     if (debugRecordWriter != null) {
@@ -447,6 +447,144 @@ async function runFileReviewWithTools(params) {
     });
     return extractCompletionText(final) ?? "No issues found.";
 }
+function draftHasStructuredFindings(consolidatedText) {
+    return /-\s*\[(?:high|medium)\]/i.test(consolidatedText);
+}
+async function runVerificationWithTools(params) {
+    const { openaiInstance, aiModel, baseMessages, refs, gitLabProjectApiUrl, projectId, headers, forceTools, consolidatedDraft, loggers, debugDumpFile, debugRecordWriter, } = params;
+    const { logDebug, logStep } = loggers;
+    const messages = [...baseMessages];
+    const tools = [
+        {
+            type: "function",
+            function: {
+                name: TOOL_NAME_GET_FILE,
+                description: "Fetch raw file content at a specific git ref for review context.",
+                parameters: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        path: { type: "string", description: "Repository file path." },
+                        ref: {
+                            type: "string",
+                            description: `Git ref or sha. Prefer "${refs.base}" (base) or "${refs.head}" (head).`,
+                        },
+                    },
+                    required: ["path", "ref"],
+                },
+            },
+        },
+        {
+            type: "function",
+            function: {
+                name: TOOL_NAME_GREP,
+                description: "Search the repository for a keyword or pattern. Returns up to 10 matching code fragments with file paths and line numbers.",
+                parameters: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "Search string (keyword, function name, variable, etc.).",
+                        },
+                        ref: {
+                            type: "string",
+                            description: `Git ref to search in. Prefer "${refs.head}" (head).`,
+                        },
+                    },
+                    required: ["query"],
+                },
+            },
+        },
+    ];
+    const verificationForceRound0 = forceTools && draftHasStructuredFindings(consolidatedDraft);
+    for (let round = 0; round < MAX_VERIFICATION_TOOL_ROUNDS; round += 1) {
+        const completion = await createCompletionWithDebug({
+            openaiInstance,
+            requestLabel: `verification_pass_round_${round + 1}`,
+            debugDumpFile,
+            debugRecordWriter,
+            request: {
+                model: aiModel,
+                temperature: 0,
+                stream: false,
+                messages,
+                tools,
+                tool_choice: verificationForceRound0 && round === 0 ? "required" : "auto",
+            },
+        });
+        const message = completion.choices[0]?.message;
+        if (message == null)
+            return completion;
+        const toolCalls = message.tool_calls ?? [];
+        logDebug(`verification round=${round + 1} tool_calls=${toolCalls.length} finish_reason=${completion.choices[0]?.finish_reason ?? "unknown"}`);
+        if (toolCalls.length === 0)
+            return completion;
+        messages.push({
+            role: "assistant",
+            content: message.content ?? "",
+            tool_calls: toolCalls,
+        });
+        for (const toolCall of toolCalls) {
+            if (toolCall.type !== "function")
+                continue;
+            const toolName = toolCall.function.name;
+            const argsRaw = toolCall.function.arguments ?? "{}";
+            await appendDebugDump(debugDumpFile, debugRecordWriter, {
+                kind: "tool_call",
+                phase: "verification",
+                round: round + 1,
+                id: toolCall.id,
+                name: toolName,
+                arguments: argsRaw,
+            });
+            logToolUsageMinimal(logStep, toolName, argsRaw, "(verify)");
+            let toolContent;
+            if (toolName === TOOL_NAME_GET_FILE) {
+                toolContent = await handleGetFileTool(argsRaw, gitLabProjectApiUrl, headers);
+            }
+            else if (toolName === TOOL_NAME_GREP) {
+                toolContent = await handleGrepTool(argsRaw, refs.head, gitLabProjectApiUrl, headers, projectId);
+            }
+            else {
+                toolContent = JSON.stringify({
+                    ok: false,
+                    error: `Unknown tool "${toolName}"`,
+                });
+            }
+            messages.push({
+                role: "tool",
+                tool_call_id: toolCall.id,
+                content: toolContent,
+            });
+            await appendDebugDump(debugDumpFile, debugRecordWriter, {
+                kind: "tool_response",
+                phase: "verification",
+                round: round + 1,
+                id: toolCall.id,
+                name: toolName,
+                content: toolContent,
+            });
+            logDebug(`verification tool id=${toolCall.id} name=${toolName} payload=${toolContent.slice(0, 300)}`);
+        }
+    }
+    messages.push({
+        role: "user",
+        content: `Tool-call limit reached (${MAX_VERIFICATION_TOOL_ROUNDS}). Do not call tools. Output only the verified findings in the required format.`,
+    });
+    return createCompletionWithDebug({
+        openaiInstance,
+        requestLabel: "verification_pass_final_after_tool_limit",
+        debugDumpFile,
+        debugRecordWriter,
+        request: {
+            model: aiModel,
+            temperature: 0,
+            stream: false,
+            messages,
+        },
+    });
+}
 export async function reviewMergeRequestMultiPass(params) {
     const { openaiInstance, aiModel, promptLimits, changes, refs, gitLabProjectApiUrl, projectId, headers, maxFindings, reviewConcurrency, forceTools, loggers, debugDumpFile, debugRecordWriter, } = params;
     const { logStep } = loggers;
@@ -555,25 +693,28 @@ export async function reviewMergeRequestMultiPass(params) {
         if (consolidatedText == null || consolidatedText.trim() === "") {
             return buildAnswer(consolidateCompletion);
         }
-        logStep("Pass 4/4: verifying consolidated findings");
+        logStep("Pass 4/4: verifying consolidated findings (repo tools)");
         const verificationMessages = buildVerificationPrompt({
             perFileFindings,
             summary: triageResult.summary,
             consolidatedFindings: consolidatedText,
             maxFindings,
+            refs,
         });
         try {
-            const verificationCompletion = await createCompletionWithDebug({
+            const verificationCompletion = await runVerificationWithTools({
                 openaiInstance,
-                requestLabel: "verification_pass",
+                aiModel,
+                baseMessages: verificationMessages,
+                refs,
+                gitLabProjectApiUrl,
+                projectId,
+                headers,
+                forceTools,
+                consolidatedDraft: consolidatedText,
+                loggers,
                 debugDumpFile,
                 debugRecordWriter,
-                request: {
-                    model: aiModel,
-                    temperature: 0.0,
-                    stream: false,
-                    messages: verificationMessages,
-                },
             });
             return buildAnswer(verificationCompletion);
         }

package/dist/cli/debug-artifacts-html.js

@@ -76,8 +76,34 @@ export async function renderDebugArtifactsHtml(params) {
     const fileServerLabel = Array.from(byLabel.keys()).find((k) => k.startsWith("file_review_server.js_round_"));
     const fileCiLabel = Array.from(byLabel.keys()).find((k) => k.startsWith("file_review_.gitlab-ci.yml_round_"));
     const consolidateLabel = "consolidate_pass";
-    const verificationLabel = "verification_pass";
-    const finalStatus = getContent(verificationLabel).trim() !== "" ? "Verified" : "Fallback";
+    function pickVerificationSection() {
+        const afterLimit = getContent("verification_pass_final_after_tool_limit");
+        if (afterLimit.trim() !== "")
+            return {
+                label: "verification_pass_final_after_tool_limit",
+                content: afterLimit,
+            };
+        const roundLabels = Array.from(byLabel.keys())
+            .filter((k) => k.startsWith("verification_pass_round_"))
+            .sort((a, b) => {
+            const na = Number(a.replace("verification_pass_round_", ""));
+            const nb = Number(b.replace("verification_pass_round_", ""));
+            return na - nb;
+        });
+        for (let i = roundLabels.length - 1; i >= 0; i--) {
+            const lbl = roundLabels[i];
+            const c = getContent(lbl);
+            if (c.trim() !== "")
+                return { label: lbl, content: c };
+        }
+        const legacy = getContent("verification_pass");
+        if (legacy.trim() !== "")
+            return { label: "verification_pass", content: legacy };
+        return { label: "verification_pass_round_1", content: "" };
+    }
+    const verificationSection = pickVerificationSection();
+    const verificationLabel = verificationSection.label;
+    const finalStatus = verificationSection.content.trim() !== "" ? "Verified" : "Fallback";
     const html = `<!doctype html>
 <html lang="en">
 <head>
@@ -141,7 +167,7 @@ export async function renderDebugArtifactsHtml(params) {
     <h2>Pass 4 — Verification</h2>
     <div class="section">
       <div class="row"><span class="badge">label: ${escapeHtml(verificationLabel)}</span><span class="tokens">${escapeHtml(getTokenTriplet(verificationLabel))}</span></div>
-      ${renderFindings(getContent(verificationLabel))}
+      ${renderFindings(verificationSection.content)}
     </div>
   </div>
 </body>

package/dist/cli/tooling.js

@@ -3,6 +3,8 @@ export const TOOL_NAME_GET_FILE = "get_file_at_ref";
 export const TOOL_NAME_GREP = "grep_repository";
 export const MAX_TOOL_ROUNDS = 12;
 export const MAX_FILE_TOOL_ROUNDS = 5;
+/** Pass 4 (verification): confirm drafts against repo without duplicating main-review depth. */
+export const MAX_VERIFICATION_TOOL_ROUNDS = 10;
 export function logToolUsageMinimal(logStep, toolName, argsRaw, contextFile) {
     try {
         const parsed = JSON.parse(argsRaw);

package/dist/cli.js

@@ -78,7 +78,7 @@ async function main() {
     const reviewConcurrency = parseNumberFlag(process.argv, "max-review-concurrency", DEFAULT_REVIEW_CONCURRENCY, 1);
     const aiModel = envOrDefault("AI_MODEL", "gpt-4o-mini");
     const artifactHtmlFile = INCLUDE_ARTIFACTS
-        ? envOrDefault("AI_REVIEW_ARTIFACT_HTML_FILE", ".ai-review-debug.html")
+        ? envOrDefault("AI_REVIEW_ARTIFACT_HTML_FILE", "ai-review-report.html")
         : undefined;
     const artifactRecords = [];
     const debugRecordWriter = INCLUDE_ARTIFACTS

package/dist/prompt/index.js

@@ -126,7 +126,7 @@ export function buildConsolidatePrompt(params) {
     ];
 }
 export function buildVerificationPrompt(params) {
-    const { perFileFindings, summary, consolidatedFindings, maxFindings } = params;
+    const { perFileFindings, summary, consolidatedFindings, maxFindings, refs, } = params;
     const findingsText = perFileFindings
         .map((f) => `### ${f.path}\n${f.findings}`)
         .join("\n\n");
@@ -141,6 +141,7 @@ export function buildVerificationPrompt(params) {
                 summary,
                 findingsText,
                 consolidatedFindings,
+                refs,
             }),
         },
     ];

package/dist/prompt/templates/postprocess-system.js

@@ -20,8 +20,10 @@ export function buildVerificationSystemLines(maxFindings) {
     return [
         "You are a skeptical verifier of a merge request review.",
         "Your job is to remove weak, speculative, or unsupported findings from the draft list.",
+        "Tools get_file_at_ref and grep_repository are available. Use them to check claims about current code against the repository at the MR head ref.",
+        "Drop a finding if file contents at refs.head contradict it, or if it cannot be verified after reasonable tool use.",
         "Do not add new findings. Keep, rewrite for clarity, or remove existing findings only.",
-        "A finding can stay only if it is directly supported by evidence from the per-file findings.",
+        "A finding can stay only if supported by the per-file evidence pool and not contradicted by tools when the claim is about code that exists at refs.head.",
         "If confidence is not high, drop the finding.",
         "Preserve this exact per-finding markdown block:",
         "`- [high|medium] <title>`",

package/dist/prompt/templates/user-prompts.js

@@ -57,10 +57,12 @@ export function buildConsolidateUserContent(params) {
     ].join("\n");
 }
 export function buildVerificationUserContent(params) {
-    const { summary, findingsText, consolidatedFindings } = params;
+    const { summary, findingsText, consolidatedFindings, refs } = params;
     return [
         `MR Summary: ${summary}`,
         "",
+        `Refs for tools: head (post-change)="${refs.head}", base="${refs.base}". Prefer head when checking whether the issue exists in the MR.`,
+        "",
         "Per-file findings (evidence pool):",
         findingsText,
         "",

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@krotovm/gitlab-ai-review",
-  "version": "1.0.26",
+  "version": "1.0.27",
   "description": "CLI tool to generate AI code reviews for GitLab merge requests.",
   "main": "dist/cli.js",
   "bin": {