@krotovm/gitlab-ai-review 1.0.33 → 1.0.35

package/README.md

@@ -75,6 +75,7 @@ GitLab provides these automatically in Merge Request pipelines:
 - `--max-diffs=50` - Max number of diffs included in the prompt.
 - `--max-diff-chars=16000` - Max chars per diff chunk (single-pass fallback only).
 - `--max-total-prompt-chars=220000` - Final hard cap for prompt size (single-pass fallback only).
+- `--triage-diff-chars=2000` - Max chars per file diff sent to the triage pass (Pass 1). Increase for large diffs where the first hunks are mostly git headers.
 - `--max-findings=5` - Max findings in the final review (CI multi-pass only).
 - `--max-review-concurrency=5` - Parallel per-file review API calls (CI multi-pass only).
 - `--debug` - Print full error details (stack and API error fields).
@@ -85,8 +86,8 @@ GitLab provides these automatically in Merge Request pipelines:
 
 The reviewer uses a three-pass pipeline optimized for large merge requests:
 
-1. **Triage** - A fast LLM pass classifies each changed file as `NEEDS_REVIEW` or `SKIP` and generates a short MR summary.
-2. **Per-file review** - Only `NEEDS_REVIEW` files are reviewed, each in a dedicated LLM call running in parallel (with tools to fetch full files or grep the repository).
+1. **Triage** - A fast LLM pass classifies each changed file as `NEEDS_REVIEW` or `SKIP`, with a per-file `reason`, and generates a short MR summary. Each file diff is truncated to `--triage-diff-chars` (default 2000).
+2. **Per-file review** - Only `NEEDS_REVIEW` files are reviewed (if triage marks every file `SKIP`, all files are reviewed anyway). Each reviewed file gets a dedicated LLM call running in parallel (with tools to fetch full files or grep the repository).
 3. **Consolidate** - Per-file findings are merged, deduplicated, ranked by severity, and trimmed to top N (default 5).
 
 If the triage pass fails (API error, unparseable response), the pipeline falls back to the original single-pass approach automatically.

package/dist/cli/args.js

@@ -1,5 +1,5 @@
 /** @format */
-import { DEFAULT_PROMPT_LIMITS, parsePromptProfile as parsePromptProfileValue, } from "../prompt/index.js";
+import { DEFAULT_PROMPT_LIMITS, DEFAULT_TRIAGE_DIFF_CHARS, parsePromptProfile as parsePromptProfileValue, } from "../prompt/index.js";
 export function requireEnvs(names) {
     const missing = names.filter((name) => {
         const value = process.env[name];
@@ -87,6 +87,9 @@ export function parsePromptLimits(argv) {
         maxTotalPromptChars: parseNumberFlag(argv, "max-total-prompt-chars", DEFAULT_PROMPT_LIMITS.maxTotalPromptChars, 1),
     };
 }
+export function parseTriageDiffChars(argv) {
+    return parseNumberFlag(argv, "triage-diff-chars", DEFAULT_TRIAGE_DIFF_CHARS, 1);
+}
 export function hasIgnoredExtension(filePath, ignoredExtensions) {
     const lowerPath = filePath.toLowerCase();
     return ignoredExtensions.some((ext) => lowerPath.endsWith(ext));

package/dist/cli/ci-review.js

@@ -3,6 +3,51 @@ import OpenAI from "openai";
 import { buildAnswer, buildConsolidatePrompt, buildFileReviewPrompt, buildPrompt, buildTriagePrompt, buildVerificationPrompt, DEFAULT_PROMPT_PROFILE, extractCompletionText, isEmptyReviewBody, NO_FINDINGS_SENTENCE, parseTriageResponseDetailed, parseTriageResponse, } from "../prompt/index.js";
 import { fetchFileAtRef, searchRepository, } from "../gitlab/services.js";
 import { logToolUsageMinimal, MAX_FILE_TOOL_ROUNDS, MAX_TOOL_ROUNDS, MAX_VERIFICATION_TOOL_ROUNDS, TOOL_NAME_GET_FILE, TOOL_NAME_GREP, } from "./tooling.js";
+function buildTriageDecisions(params) {
+    const { changes, triageResult } = params;
+    const triageMap = new Map(triageResult.files.map((f) => [f.path, f]));
+    let reviewFiles = changes.filter((c) => triageMap.get(c.new_path)?.verdict !== "SKIP");
+    const skipAllOverride = reviewFiles.length === 0;
+    if (skipAllOverride)
+        reviewFiles = changes;
+    const decisions = changes.map((change) => {
+        const path = change.new_path;
+        const triageFile = triageMap.get(path);
+        const verdict = triageFile?.verdict ?? "NEEDS_REVIEW";
+        const reason = triageFile?.reason ??
+            (triageFile == null ? "not listed in triage response" : undefined);
+        let review_action;
+        if (verdict === "NEEDS_REVIEW" || triageFile == null) {
+            review_action = "review";
+        }
+        else if (skipAllOverride) {
+            review_action = "reviewed_via_override";
+        }
+        else {
+            review_action = "skipped";
+        }
+        return {
+            path,
+            verdict,
+            ...(reason != null ? { reason } : {}),
+            review_action,
+        };
+    });
+    return { decisions, skipAllOverride, reviewFiles };
+}
+function formatTriageDecisionLine(decision) {
+    const reasonSuffix = decision.reason != null && decision.reason !== ""
+        ? ` — ${decision.reason}`
+        : "";
+    switch (decision.review_action) {
+        case "skipped":
+            return `  Skipped: ${decision.path} (${decision.verdict})${reasonSuffix}`;
+        case "reviewed_via_override":
+            return `  Reviewed via override: ${decision.path} (triage=${decision.verdict})${reasonSuffix}`;
+        default:
+            return `  Review: ${decision.path} (${decision.verdict})${reasonSuffix}`;
+    }
+}
 async function appendDebugDump(_debugDumpFile, debugRecordWriter, record) {
     const withTs = { ts: new Date().toISOString(), ...record };
     if (debugRecordWriter != null) {
@@ -16,8 +61,13 @@ async function createCompletionWithDebug(params) {
         label: requestLabel,
         request,
     });
+    // Stream and reassemble: reverse proxies (nginx proxy_read_timeout) return 504 on
+    // long silent non-streamed completions; streamed chunks keep the connection alive.
+    const { stream: _stream, ...createParams } = request;
     try {
-        const completion = await openaiInstance.chat.completions.create(request);
+        const completion = await openaiInstance.chat.completions
+            .stream(createParams)
+            .finalChatCompletion();
         await appendDebugDump(debugDumpFile, debugRecordWriter, {
             kind: "openai_response",
             label: requestLabel,
@@ -592,9 +642,10 @@ async function runVerificationWithTools(params) {
     });
 }
 export async function reviewMergeRequestMultiPass(params) {
-    const { openaiInstance, aiModel, promptLimits, changes, refs, gitLabProjectApiUrl, projectId, headers, maxFindings, reviewConcurrency, forceTools, promptProfile = DEFAULT_PROMPT_PROFILE, loggers, debugDumpFile, debugRecordWriter, } = params;
+    const { openaiInstance, aiModel, promptLimits, triageDiffChars, changes, refs, gitLabProjectApiUrl, projectId, headers, maxFindings, reviewConcurrency, forceTools, promptProfile = DEFAULT_PROMPT_PROFILE, loggers, debugDumpFile, debugRecordWriter, } = params;
     const { logStep } = loggers;
-    logStep(`Pass 1/4: triaging ${changes.length} file(s) (prompt profile=${promptProfile})`);
+    logStep(`Pass 1/4: triaging ${changes.length} file(s) ` +
+        `(prompt profile=${promptProfile}, triage_diff_chars=${triageDiffChars})`);
     const triageInputs = changes.map((c) => ({
         path: c.new_path,
         new_file: c.new_file,
@@ -602,7 +653,7 @@ export async function reviewMergeRequestMultiPass(params) {
         renamed_file: c.renamed_file,
         diff: c.diff,
     }));
-    const triageMessages = buildTriagePrompt(triageInputs, promptProfile);
+    const triageMessages = buildTriagePrompt(triageInputs, promptProfile, triageDiffChars);
     let triageResult = null;
     let triageText = null;
     let triageParseReason = null;
@@ -662,39 +713,69 @@ export async function reviewMergeRequestMultiPass(params) {
             debugRecordWriter,
         });
     }
-    const triageMap = new Map(triageResult.files.map((f) => [f.path, f.verdict]));
-    let reviewFiles = changes.filter((c) => triageMap.get(c.new_path) !== "SKIP");
-    const skippedCount = changes.length - reviewFiles.length;
-    if (reviewFiles.length === 0) {
+    const { decisions, skipAllOverride, reviewFiles } = buildTriageDecisions({
+        changes,
+        triageResult,
+    });
+    const skippedCount = decisions.filter((d) => d.review_action === "skipped").length;
+    await appendDebugDump(debugDumpFile, debugRecordWriter, {
+        kind: "triage_decision",
+        summary: triageResult.summary,
+        skip_all_override: skipAllOverride,
+        triage_diff_chars: triageDiffChars,
+        files: decisions,
+    });
+    if (skipAllOverride) {
         logStep(`Triage wanted to skip all ${changes.length} file(s) — overriding to review all. Summary: ${triageResult.summary.slice(0, 120)}...`);
-        reviewFiles = changes;
     }
     else {
         logStep(`Triage: ${reviewFiles.length} file(s) to review, ${skippedCount} skipped. Summary: ${triageResult.summary.slice(0, 120)}...`);
     }
+    for (const decision of decisions) {
+        if (decision.review_action === "review")
+            continue;
+        logStep(formatTriageDecisionLine(decision));
+    }
     logStep(`Pass 2/4: reviewing ${reviewFiles.length} file(s) (concurrency=${reviewConcurrency})`);
     const allChangedPaths = changes.map((c) => c.new_path);
+    const failedPaths = [];
     const perFileFindings = await mapWithConcurrency(reviewFiles, reviewConcurrency, async (change) => {
         const otherFiles = allChangedPaths.filter((p) => p !== change.new_path);
-        const findings = await runFileReviewWithTools({
-            openaiInstance,
-            aiModel,
-            filePath: change.new_path,
-            fileDiff: change.diff,
-            summary: triageResult.summary,
-            otherChangedFiles: otherFiles,
-            refs,
-            gitLabProjectApiUrl,
-            projectId,
-            headers,
-            forceTools,
-            promptProfile,
-            loggers,
-            debugDumpFile,
-            debugRecordWriter,
-        });
+        let findings;
+        try {
+            findings = await runFileReviewWithTools({
+                openaiInstance,
+                aiModel,
+                filePath: change.new_path,
+                fileDiff: change.diff,
+                summary: triageResult.summary,
+                otherChangedFiles: otherFiles,
+                refs,
+                gitLabProjectApiUrl,
+                projectId,
+                headers,
+                forceTools,
+                promptProfile,
+                loggers,
+                debugDumpFile,
+                debugRecordWriter,
+            });
+        }
+        catch (error) {
+            const preview = String(error?.message ?? error)
+                .replace(/\s+/g, " ")
+                .slice(0, 200);
+            logStep(`Pass 2: review failed for ${change.new_path}: ${preview}. Continuing with remaining files.`);
+            failedPaths.push(change.new_path);
+            // ponytail: failed file surfaces as "no findings" in the MR comment;
+            // thread failedPaths into the consolidate prompt if that ever matters.
+            findings = NO_FINDINGS_SENTENCE;
+        }
         return { path: change.new_path, findings };
     });
+    if (failedPaths.length === reviewFiles.length) {
+        throw new Error(`All ${reviewFiles.length} per-file reviews failed (e.g. ${failedPaths[0]}). See log above.`);
+    }
     logStep("Pass 3/4: consolidating findings");
     const consolidateMessages = buildConsolidatePrompt({
         perFileFindings,

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

@@ -50,6 +50,58 @@ export async function renderDebugArtifactsHtml(params) {
             return value;
         }
     }
+    function renderTriageDecisions() {
+        const decisionRecord = records.find((r) => r.kind === "triage_decision");
+        if (decisionRecord == null)
+            return "<pre>No triage decision record</pre>";
+        const summary = typeof decisionRecord.summary === "string" ? decisionRecord.summary : "";
+        const skipAllOverride = decisionRecord.skip_all_override === true;
+        const triageDiffChars = Number(decisionRecord.triage_diff_chars ?? 0);
+        const files = Array.isArray(decisionRecord.files) ? decisionRecord.files : [];
+        const actionLabel = (action) => {
+            switch (action) {
+                case "skipped":
+                    return "Skipped";
+                case "reviewed_via_override":
+                    return "Reviewed (override)";
+                case "review":
+                    return "Review";
+                default:
+                    return String(action ?? "unknown");
+            }
+        };
+        const rows = files
+            .map((file) => {
+            const path = typeof file.path === "string" ? file.path : "?";
+            const verdict = typeof file.verdict === "string" ? file.verdict : "?";
+            const reason = typeof file.reason === "string" ? file.reason : "";
+            const action = actionLabel(file.review_action);
+            return `<tr>
+          <td><code>${escapeHtml(path)}</code></td>
+          <td>${escapeHtml(verdict)}</td>
+          <td>${escapeHtml(action)}</td>
+          <td>${escapeHtml(reason)}</td>
+        </tr>`;
+        })
+            .join("\n");
+        const overrideNote = skipAllOverride
+            ? `<p class="tokens" style="margin:0 0 10px;color:var(--med);">All files were marked SKIP — pipeline overrode and reviewed every file.</p>`
+            : "";
+        return `${overrideNote}
+      <p class="tokens" style="margin:0 0 10px;">triage_diff_chars=${escapeHtml(String(triageDiffChars))}</p>
+      <p style="margin:0 0 12px;">${escapeHtml(summary)}</p>
+      <table style="width:100%;border-collapse:collapse;font-size:13px;">
+        <thead>
+          <tr style="text-align:left;color:var(--muted);">
+            <th style="padding:6px 8px;border-bottom:1px solid var(--line);">File</th>
+            <th style="padding:6px 8px;border-bottom:1px solid var(--line);">Verdict</th>
+            <th style="padding:6px 8px;border-bottom:1px solid var(--line);">Action</th>
+            <th style="padding:6px 8px;border-bottom:1px solid var(--line);">Reason</th>
+          </tr>
+        </thead>
+        <tbody>${rows}</tbody>
+      </table>`;
+    }
     function renderFindings(markdown) {
         const trimmed = markdown.trim();
         if (trimmed === "")
@@ -144,7 +196,12 @@ export async function renderDebugArtifactsHtml(params) {
       <div class="tokens" style="margin-top:6px;"><strong>Total:</strong> ${escapeHtml(totalTokens.toLocaleString())} tokens</div>
     </div>
 
-    <h2>Pass 1 — Triage</h2>
+    <h2>Pass 1 — Triage Decisions</h2>
+    <div class="section">
+      ${renderTriageDecisions()}
+    </div>
+
+    <h2>Pass 1 — Triage (raw model output)</h2>
     <div class="section">
       <div class="row"><span class="badge">label: triage_pass</span><span class="tokens">${escapeHtml(findTs("triage_pass"))}</span></div>
       <pre>${escapeHtml(triageContentPretty)}</pre>

package/dist/cli.js

@@ -3,7 +3,7 @@
 import OpenAI from "openai";
 import { readFile } from "node:fs/promises";
 import { DEFAULT_MAX_FINDINGS, DEFAULT_REVIEW_CONCURRENCY, } from "./prompt/index.js";
-import { envOrDefault, envOrUndefined, hasDebugFlag, hasForceToolsFlag, hasIncludeArtifactsFlag, hasIgnoredExtension, parseIgnoreExtensions, parseNumberFlag, parsePromptLimits, readPromptProfileFromEnv, requireEnvs, } from "./cli/args.js";
+import { envOrDefault, envOrUndefined, hasDebugFlag, hasForceToolsFlag, hasIncludeArtifactsFlag, hasIgnoredExtension, parseIgnoreExtensions, parseNumberFlag, parsePromptLimits, parseTriageDiffChars, readPromptProfileFromEnv, requireEnvs, } from "./cli/args.js";
 import { reviewMergeRequestMultiPass } from "./cli/ci-review.js";
 import { fetchMergeRequestChanges, postMergeRequestNote, } from "./gitlab/services.js";
 import { renderDebugArtifactsHtml } from "./cli/debug-artifacts-html.js";
@@ -25,6 +25,7 @@ function printHelp() {
         "  --max-diffs=50",
         "  --max-diff-chars=16000",
         "  --max-total-prompt-chars=220000",
+        "  --triage-diff-chars=2000   Max chars per file diff in triage pass (Pass 1).",
         "  --max-findings=5          Max findings in final review (CI multi-pass only).",
         "  --max-review-concurrency=5  Parallel per-file review calls (CI multi-pass only).",
         "",
@@ -77,6 +78,7 @@ async function main() {
     logStep(`gitlab-ai-review v${cliVersion}`);
     const ignoredExtensions = parseIgnoreExtensions(process.argv);
     const promptLimits = parsePromptLimits(process.argv);
+    const triageDiffChars = parseTriageDiffChars(process.argv);
     const maxFindings = parseNumberFlag(process.argv, "max-findings", DEFAULT_MAX_FINDINGS, 1);
     const reviewConcurrency = parseNumberFlag(process.argv, "max-review-concurrency", DEFAULT_REVIEW_CONCURRENCY, 1);
     const aiModel = envOrDefault("AI_MODEL", "gpt-4o-mini");
@@ -134,6 +136,7 @@ async function main() {
             openaiInstance: new OpenAI({ apiKey: openaiApiKey }),
             aiModel,
             promptLimits,
+            triageDiffChars,
             changes: filteredChanges,
             refs: {
                 base: mrChanges.diff_refs?.base_sha ?? "HEAD",

package/dist/prompt/index.js

@@ -10,6 +10,8 @@ export const DEFAULT_PROMPT_LIMITS = {
     maxDiffChars: 16000,
     maxTotalPromptChars: 220000,
 };
+/** Max chars of each file diff sent to the triage pass (Pass 1). */
+export const DEFAULT_TRIAGE_DIFF_CHARS = 2000;
 export const AI_MODEL_TEMPERATURE = 0.2;
 export const AI_MAX_OUTPUT_TOKENS = 600;
 export const buildPrompt = ({ changes, limits, allowTools = false, profile = DEFAULT_PROMPT_PROFILE, }) => {
@@ -52,12 +54,12 @@ export const buildPrompt = ({ changes, limits, allowTools = false, profile = DEF
 // ---------------------------------------------------------------------------
 export const DEFAULT_MAX_FINDINGS = 5;
 export const DEFAULT_REVIEW_CONCURRENCY = 5;
-export function buildTriagePrompt(changes, profile = DEFAULT_PROMPT_PROFILE) {
+export function buildTriagePrompt(changes, profile = DEFAULT_PROMPT_PROFILE, triageDiffChars = DEFAULT_TRIAGE_DIFF_CHARS) {
     return [
         buildTriageSystemMessage(profile),
         {
             role: "user",
-            content: buildTriageUserContent(changes),
+            content: buildTriageUserContent(changes, triageDiffChars),
         },
     ];
 }
@@ -115,6 +117,9 @@ export function parseTriageResponseDetailed(text) {
                     .map((f) => ({
                     path: f.path,
                     verdict: f.verdict,
+                    ...(typeof f.reason === "string" && f.reason.trim() !== ""
+                        ? { reason: f.reason.trim() }
+                        : {}),
                 })),
             },
             reason: null,

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

@@ -6,7 +6,9 @@ const DEFAULT_LINES = [
     "Also produce a concise summary (2-4 sentences) of the entire merge request: what it does and which areas it touches.",
     "",
     "Respond with a JSON object (no markdown fences, no prose before or after) in this exact schema:",
-    '{ "summary": "<MR summary>", "files": [{ "path": "<file path>", "verdict": "NEEDS_REVIEW" | "SKIP" }] }',
+    '{ "summary": "<MR summary>", "files": [{ "path": "<file path>", "verdict": "NEEDS_REVIEW" | "SKIP", "reason": "<one short sentence explaining the verdict>" }] }',
+    "",
+    "The reason field is required for every file — cite what you saw in the diff (e.g. \"import reordering only\" or \"changes Input props and validation\").",
     "",
     "Rules:",
     "- When in doubt, verdict is NEEDS_REVIEW.",
@@ -20,13 +22,13 @@ const DEFAULT_LINES = [
     "- Config/CI/docs files are SKIP unless they modify build targets, env vars, or secrets.",
     "",
     "Example output (copy this style exactly — single JSON object, no fences, no preamble):",
-    '{"summary":"Adds retry-with-backoff to the OpenAI client and updates the README badge.","files":[{"path":"src/openai/client.ts","verdict":"NEEDS_REVIEW"},{"path":"README.md","verdict":"SKIP"}]}',
+    '{"summary":"Adds retry-with-backoff to the OpenAI client and updates the README badge.","files":[{"path":"src/openai/client.ts","verdict":"NEEDS_REVIEW","reason":"adds retry loop and error handling in API client"},{"path":"README.md","verdict":"SKIP","reason":"badge URL change only"}]}',
 ];
 const WEAK_LINES = [
     "You triage merge-request files. Output one JSON object only — no prose, no markdown, no code fences, no preamble.",
     "",
     "Schema (use exactly these keys):",
-    '{"summary":"<2-3 sentences about the MR>","files":[{"path":"<file path>","verdict":"NEEDS_REVIEW" | "SKIP"}]}',
+    '{"summary":"<2-3 sentences about the MR>","files":[{"path":"<file path>","verdict":"NEEDS_REVIEW" | "SKIP","reason":"<one short sentence>"}]}',
     "",
     "Mark a file NEEDS_REVIEW when ANY of these is true:",
     "- the diff adds or removes non-comment lines,",
@@ -39,7 +41,7 @@ const WEAK_LINES = [
     "When in doubt, choose NEEDS_REVIEW.",
     "",
     "Example output (copy this exactly — one line, one JSON object, nothing else):",
-    '{"summary":"Adds retry-with-backoff to the OpenAI client and updates the README badge.","files":[{"path":"src/openai/client.ts","verdict":"NEEDS_REVIEW"},{"path":"README.md","verdict":"SKIP"}]}',
+    '{"summary":"Adds retry-with-backoff to the OpenAI client and updates the README badge.","files":[{"path":"src/openai/client.ts","verdict":"NEEDS_REVIEW","reason":"adds retry loop in API client"},{"path":"README.md","verdict":"SKIP","reason":"badge URL only"}]}',
 ];
 export function getTriageSystemLines(profile) {
     return profile === "weak" ? WEAK_LINES : DEFAULT_LINES;

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

@@ -1,4 +1,5 @@
 /** @format */
+import { truncateWithMarker } from "../utils.js";
 export function buildMainReviewUserContent(params) {
     const { stats, toolNote, changesText } = params;
     return [
@@ -11,7 +12,7 @@ export function buildMainReviewUserContent(params) {
         "Produce your review now. Follow the system instructions strictly.",
     ].join("\n");
 }
-export function buildTriageUserContent(changes) {
+export function buildTriageUserContent(changes, maxDiffChars) {
     const fileEntries = changes.map((c) => {
         const flags = [];
         if (c.new_file)
@@ -21,9 +22,8 @@ export function buildTriageUserContent(changes) {
         if (c.renamed_file)
             flags.push("renamed");
         const flagStr = flags.length > 0 ? ` [${flags.join(", ")}]` : "";
-        const snippet = c.diff.slice(0, 300);
-        const truncNote = c.diff.length > 300 ? "..." : "";
-        return `### ${c.path}${flagStr}\n\`\`\`\n${snippet}${truncNote}\n\`\`\``;
+        const snippet = truncateWithMarker(c.diff, maxDiffChars, c.path);
+        return `### ${c.path}${flagStr}\n\`\`\`diff\n${snippet}\n\`\`\``;
     });
     return `Triage these ${changes.length} file(s):\n\n${fileEntries.join("\n\n")}`;
 }

package/package.json

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