@krotovm/gitlab-ai-review 1.0.43 → 1.0.44

package/README.md

@@ -41,7 +41,7 @@ Or include it as a [CI/CD component from the GitLab Catalog](https://gitlab.com/
 
 ```yaml
 include:
-  - component: gitlab.com/KrotovM/gitlab-ai-review/review@1.0.2
+  - component: gitlab.com/KrotovM/gitlab-ai-review/review@1.0.3
     inputs:
       args: "--include-artifacts"
 ```
@@ -101,8 +101,18 @@ GitLab provides these automatically in Merge Request pipelines:
 - `--max-review-concurrency=2` - Parallel per-file review API calls (CI multi-pass only). Set to 1 for single-GPU backends that queue-starve long requests.
 - `--debug` - Print full error details (stack and API error fields).
 - `--include-artifacts` - Generate a local HTML debug artifact with per-pass outputs/tokens.
+- `--inline-comments` - Post findings on changed lines as resolvable diff threads; the rest stays in the summary comment. See [Inline comments](#inline-comments).
 - `--help` - Show help output.
 
+## Inline comments
+
+With `--inline-comments`, each finding whose line falls inside the MR diff becomes a resolvable diff thread. Findings outside the diff (unchanged code, other files) stay in the summary comment, which also counts the threads. On later runs:
+
+- A finding is not posted again when an AI thread already sits within 3 lines of it on unchanged code — open or resolved, so resolving a false positive dismisses it.
+- An open AI thread whose code changed (GitLab shows it as outdated) is resolved automatically with a short reply, unless someone replied to it; if you reopen it afterwards, later runs leave it alone. If the review reports the issue again, it is posted as a new thread. GitLab's own **Automatically resolve merge request diff threads when they become outdated** setting does this for every thread.
+
+Turn on **Settings → Merge requests → All threads must be resolved** to make AI findings block the merge until someone fixes or dismisses them. Line numbers come from the model, which sees numbered diffs and files, so a thread can still occasionally land a line away from the issue. Resolving threads needs a token with at least the Developer role.
+
 ## Benchmark
 
 Head-to-head against [Alibaba OpenCodeReview](https://github.com/alibaba/open-code-review) v1.8.10 (via its official GitLab CI recipe) on a demo MR with 4 seeded bugs: an auth bypass (`API_KEYS` unset → empty key accepted), a rate limiter whose window never resets, an unbounded per-IP counters Map, and a null-deref crash in a stats endpoint. Same MR, same commit range, same backends.

package/dist/cli/args.js

@@ -40,6 +40,10 @@ export function hasIncludeArtifactsFlag(argv) {
     const args = new Set(argv.slice(2));
     return args.has("--include-artifacts");
 }
+export function hasInlineCommentsFlag(argv) {
+    const args = new Set(argv.slice(2));
+    return args.has("--inline-comments");
+}
 export function parseIgnoreExtensions(argv) {
     const parsed = [];
     const args = argv.slice(2);

package/dist/cli/ci-review.js

@@ -1,6 +1,6 @@
 /** @format */
 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 { buildAnswer, buildConsolidatePrompt, buildFileReviewPrompt, buildPrompt, buildTriagePrompt, buildVerificationPrompt, DEFAULT_PROMPT_PROFILE, DISCLAIMER, extractCompletionText, isEmptyReviewBody, NO_FINDINGS_SENTENCE, parseTriageResponseDetailed, parseTriageResponse, } from "../prompt/index.js";
 import { fetchFileAtRef, searchRepository, } from "../gitlab/services.js";
 import { parseReviewFindings, truncateWithMarker } from "../prompt/utils.js";
 import { logToolFailure, logToolUsageMinimal, MAX_FILE_TOOL_ROUNDS, MAX_TOOL_ROUNDS, MAX_VERIFICATION_TOOL_ROUNDS, TOOL_NAME_GET_FILE, TOOL_NAME_GREP, } from "./tooling.js";
@@ -177,12 +177,17 @@ async function handleGetFileTool(argsRaw, gitLabProjectApiUrl, headers, logStep)
                 error: fileText.message,
             });
         }
+        // Numbered like `cat -n`, so findings cite exact lines instead of counted ones.
+        const numbered = fileText
+            .split("\n")
+            .map((line, i) => `${i + 1}\t${line}`)
+            .join("\n");
         return JSON.stringify({
             ok: true,
             path,
             ref,
-            content: fileText.slice(0, MAX_TOOL_FILE_CHARS),
-            truncated: fileText.length > MAX_TOOL_FILE_CHARS,
+            content: numbered.slice(0, MAX_TOOL_FILE_CHARS),
+            truncated: numbered.length > MAX_TOOL_FILE_CHARS,
         });
     }
     catch (error) {
@@ -260,7 +265,7 @@ async function reviewMergeRequestWithTools(params) {
     const { logDebug, logStep } = loggers;
     logStep(`Single-pass review started for ${changes.length} file(s) (fallback mode).`);
     const messages = buildPrompt({
-        changes: changes.map((change) => ({ diff: change.diff })),
+        changes: changes.map((change) => ({ path: change.new_path, diff: change.diff })),
         limits: promptLimits,
         allowTools: true,
         profile: promptProfile,
@@ -274,7 +279,7 @@ async function reviewMergeRequestWithTools(params) {
             type: "function",
             function: {
                 name: TOOL_NAME_GET_FILE,
-                description: "Fetch raw file content at a specific git ref for review context.",
+                description: "Fetch file content at a specific git ref for review context. Each line starts with its line number and a tab.",
                 parameters: {
                     type: "object",
                     additionalProperties: false,
@@ -419,7 +424,7 @@ async function runFileReviewWithTools(params) {
             type: "function",
             function: {
                 name: TOOL_NAME_GET_FILE,
-                description: "Fetch raw file content at a specific git ref for review context.",
+                description: "Fetch file content at a specific git ref for review context. Each line starts with its line number and a tab.",
                 parameters: {
                     type: "object",
                     additionalProperties: false,
@@ -559,7 +564,7 @@ async function runVerificationWithTools(params) {
             type: "function",
             function: {
                 name: TOOL_NAME_GET_FILE,
-                description: "Fetch raw file content at a specific git ref for review context.",
+                description: "Fetch file content at a specific git ref for review context. Each line starts with its line number and a tab.",
                 parameters: {
                     type: "object",
                     additionalProperties: false,
@@ -885,7 +890,6 @@ export async function reviewMergeRequestMultiPass(params) {
         profile: effectiveProfile,
     });
     if (consolidateMessages == null) {
-        const DISCLAIMER = "This comment was generated by AI review bot.";
         return withHeader(`${NO_FINDINGS_SENTENCE}\n\n---\n_${DISCLAIMER}_`);
     }
     try {
@@ -937,7 +941,6 @@ export async function reviewMergeRequestMultiPass(params) {
     }
     catch (error) {
         logStep(`Consolidation failed: ${error?.message ?? error}. Returning raw per-file findings.`);
-        const DISCLAIMER = "This comment was generated by AI review bot.";
         const raw = perFileFindings
             .filter((f) => !isEmptyReviewBody(f.findings))
             .map((f) => f.findings)

package/dist/cli/inline-comments.js

@@ -0,0 +1,205 @@
+/** @format */
+import { DISCLAIMER } from "../prompt/index.js";
+import { isEmptyReviewBody } from "../prompt/profile.js";
+import { parseReviewFindings, renderReviewFinding, } from "../prompt/utils.js";
+import { createMergeRequestDiscussion, fetchMergeRequestDiffRefs, listMergeRequestDiscussions, replyToMergeRequestDiscussion, resolveMergeRequestDiscussion, } from "../gitlab/services.js";
+import { logToolFailure } from "./tooling.js";
+/** Hidden marker that lets later runs recognise this tool's diff threads. */
+export const INLINE_MARKER = "<!-- gitlab-ai-review:inline -->";
+/** A finding this close to an existing AI thread counts as the same finding:
+ *  model line numbers are approximate and titles vary between runs. */
+const SAME_PLACE_LINES = 3;
+const AUTO_RESOLVED_REPLY = "Resolved automatically: the code under this thread changed. If the review reports the issue again, it opens a new thread.";
+const sameRefs = (a, b) => a.base_sha === b.base_sha &&
+    a.start_sha === b.start_sha &&
+    a.head_sha === b.head_sha;
+/** Maps every new-side line a diff thread can sit on to its old-side line
+ *  (context line) or null (added line). */
+export function mapNewLines(diff) {
+    const lines = new Map();
+    let oldLine = 0;
+    let newLine = 0;
+    for (const text of diff.split("\n")) {
+        const hunk = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(text);
+        if (hunk != null) {
+            oldLine = Number(hunk[1]);
+            newLine = Number(hunk[2]);
+        }
+        else if (newLine > 0 && text.startsWith("+")) {
+            lines.set(newLine++, null);
+        }
+        else if (newLine > 0 && text.startsWith(" ")) {
+            lines.set(newLine++, oldLine++);
+        }
+        else if (text.startsWith("-")) {
+            oldLine++;
+        }
+    }
+    return lines;
+}
+function positionFor(finding, changes, refs) {
+    const path = finding.file.replace(/`/g, "").replace(/^\.?\//, "");
+    const line = Number(/\d+/.exec(finding.line)?.[0]);
+    const change = changes.find((c) => c.new_path === path && !c.deleted_file);
+    if (change == null || !Number.isInteger(line))
+        return null;
+    const lines = mapNewLines(change.diff);
+    if (!lines.has(line))
+        return null;
+    const oldLine = lines.get(line);
+    return {
+        position_type: "text",
+        ...refs,
+        old_path: change.old_path,
+        new_path: change.new_path,
+        new_line: line,
+        ...(oldLine != null ? { old_line: oldLine } : {}),
+    };
+}
+/** Findings that are not in `post` or `known` stay in the summary comment. */
+export function planInlineComments(params) {
+    const { findings, changes, refs, discussions } = params;
+    const threads = discussions.flatMap((d) => {
+        const note = d.notes[0];
+        if (note?.position == null || !note.body.includes(INLINE_MARKER))
+            return [];
+        return [
+            {
+                id: d.id,
+                new_path: note.position.new_path,
+                new_line: note.position.new_line,
+                // GitLab moves a thread to the new diff version on every push while its
+                // line is unchanged; a thread left on older refs is outdated.
+                outdated: !sameRefs(note.position, refs),
+                resolved: note.resolved === true,
+                // GitLab adds its "changed this line" system note to the thread; any
+                // other reply (a person, or our auto-resolve note) means hands off.
+                untouched: d.notes.filter((n) => n.system !== true).length === 1,
+            },
+        ];
+    });
+    const plan = { post: [], known: [], resolve: [] };
+    for (const finding of findings) {
+        const position = positionFor(finding, changes, refs);
+        if (position == null)
+            continue;
+        const known = threads.some((t) => !t.outdated &&
+            t.new_path === position.new_path &&
+            t.new_line != null &&
+            Math.abs(t.new_line - position.new_line) <= SAME_PLACE_LINES);
+        if (known)
+            plan.known.push(finding);
+        else
+            plan.post.push({ finding, position });
+    }
+    plan.resolve = threads
+        .filter((t) => t.outdated && !t.resolved && t.untouched)
+        .map((t) => t.id);
+    return plan;
+}
+function summarize(answer, covered, counts) {
+    let body = answer;
+    for (const finding of covered) {
+        const block = renderReviewFinding(finding);
+        body = body.replace(body.includes(`${block}\n\n`) ? `${block}\n\n` : block, "");
+    }
+    const parts = [
+        counts.posted > 0 ? `${counts.posted} new` : "",
+        counts.known > 0 ? `${counts.known} already reported (open or resolved)` : "",
+        counts.resolved > 0 ? `${counts.resolved} outdated resolved` : "",
+    ].filter(Boolean);
+    if (parts.length === 0)
+        return body;
+    const note = `\n\n💬 Diff threads: ${parts.join(", ")}.`;
+    const disclaimerAt = body.lastIndexOf("\n\n---\n_");
+    return disclaimerAt === -1
+        ? body + note
+        : body.slice(0, disclaimerAt) + note + body.slice(disclaimerAt);
+}
+/** Posts findings that land on changed lines as resolvable diff threads,
+ *  resolves AI threads whose code changed, and returns the summary comment
+ *  without the findings now covered by threads. Falls back to the full
+ *  summary comment when anything goes wrong. */
+export async function postInlineFindings(params) {
+    const { answer, changes, diffRefs, logStep } = params;
+    const api = {
+        gitLabProjectApiUrl: params.gitLabProjectApiUrl,
+        headers: params.headers,
+        mergeRequestIid: params.mergeRequestIid,
+    };
+    const fallBack = (error) => {
+        logToolFailure(logStep, "inline_comments", error);
+        logStep("[inline] Posting all findings in the summary comment instead.");
+        return answer;
+    };
+    const { base_sha, start_sha, head_sha } = diffRefs ?? {};
+    if (base_sha == null || start_sha == null || head_sha == null) {
+        return fallBack(new Error("merge request has no diff refs"));
+    }
+    const refs = { base_sha, start_sha, head_sha };
+    try {
+        // List threads before re-reading the MR: GitLab moves threads only after it
+        // stores a new diff version, so a push that moved any thread we saw also
+        // shows up in the refs read below and stops this run.
+        const discussions = await listMergeRequestDiscussions(api);
+        if (discussions instanceof Error)
+            return fallBack(discussions);
+        const current = await fetchMergeRequestDiffRefs(api);
+        if (current instanceof Error)
+            return fallBack(current);
+        if (!sameRefs(current, refs)) {
+            logStep("[inline] MR has a newer diff version; posting findings in the summary comment only.");
+            return answer;
+        }
+        const findings = parseReviewFindings(answer);
+        // Only a finding whose rendered block sits in the comment verbatim can move
+        // to a thread without leaving a copy behind or unbalancing a code fence.
+        const movable = findings.filter((f) => {
+            const block = renderReviewFinding(f);
+            return answer.includes(block) && (block.match(/```/g) ?? []).length % 2 === 0;
+        });
+        const plan = planInlineComments({ findings: movable, changes, refs, discussions });
+        const posted = [];
+        for (const { finding, position } of plan.post) {
+            const body = `${renderReviewFinding(finding)}\n\n---\n_${DISCLAIMER}_\n\n${INLINE_MARKER}`;
+            const res = await createMergeRequestDiscussion({ ...api, body, position });
+            // A rejected position leaves the finding in the summary comment.
+            if (res instanceof Error)
+                logToolFailure(logStep, "inline_comments", res);
+            else
+                posted.push(finding);
+        }
+        // Resolve only after a real review whose findings could all become threads:
+        // a failed run, or an issue re-reported only in the summary, must not close
+        // threads. Header and triage-summary lines can't pass for "no findings".
+        const reviewed = movable.length === findings.length &&
+            (findings.length > 0 || isEmptyReviewBody(answer.replace(/^[#>].*$/gm, "")));
+        let resolved = 0;
+        for (const discussionId of reviewed ? plan.resolve : []) {
+            const res = await resolveMergeRequestDiscussion({ ...api, discussionId });
+            if (res instanceof Error) {
+                logToolFailure(logStep, "inline_comments", res);
+                continue;
+            }
+            resolved += 1;
+            // The reply also marks the thread as handled: if someone reopens it,
+            // later runs leave it alone.
+            const reply = await replyToMergeRequestDiscussion({
+                ...api,
+                discussionId,
+                body: AUTO_RESOLVED_REPLY,
+            });
+            if (reply instanceof Error)
+                logToolFailure(logStep, "inline_comments", reply);
+        }
+        logStep(`[inline] Diff threads: ${posted.length} new, ${plan.known.length} already reported, ${resolved} outdated resolved.`);
+        return summarize(answer, [...posted, ...plan.known], {
+            posted: posted.length,
+            known: plan.known.length,
+            resolved,
+        });
+    }
+    catch (error) {
+        return fallBack(error);
+    }
+}

package/dist/cli.js

@@ -3,8 +3,9 @@
 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, parseTriageDiffChars, readPromptProfileFromEnv, requireEnvs, } from "./cli/args.js";
+import { envOrDefault, envOrUndefined, hasDebugFlag, hasForceToolsFlag, hasIncludeArtifactsFlag, hasIgnoredExtension, hasInlineCommentsFlag, parseIgnoreExtensions, parseNumberFlag, parsePromptLimits, parseTriageDiffChars, readPromptProfileFromEnv, requireEnvs, } from "./cli/args.js";
 import { reviewMergeRequestMultiPass } from "./cli/ci-review.js";
+import { postInlineFindings } from "./cli/inline-comments.js";
 import { fetchMergeRequestChanges, postMergeRequestNote, } from "./gitlab/services.js";
 import { renderDebugArtifactsHtml } from "./cli/debug-artifacts-html.js";
 function printHelp() {
@@ -27,6 +28,7 @@ Debug:
   --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=2  Parallel per-file review calls (CI multi-pass only).
+  --inline-comments  Post findings on changed lines as resolvable diff threads; the rest stays in the summary comment.
 
 Env vars:
   OPENAI_API_KEY (required)  OpenAI API key.
@@ -47,6 +49,7 @@ CI-only env vars (provided by GitLab):
 const DEBUG_MODE = hasDebugFlag(process.argv);
 const FORCE_TOOLS = hasForceToolsFlag(process.argv);
 const INCLUDE_ARTIFACTS = hasIncludeArtifactsFlag(process.argv);
+const INLINE_COMMENTS = hasInlineCommentsFlag(process.argv);
 function logStep(message) {
     process.stdout.write(`${message}\n`);
 }
@@ -157,12 +160,23 @@ async function main() {
             loggers,
             debugRecordWriter,
         });
+        const note = INLINE_COMMENTS
+            ? await postInlineFindings({
+                answer,
+                changes: filteredChanges,
+                diffRefs: mrChanges.diff_refs,
+                gitLabProjectApiUrl,
+                headers,
+                mergeRequestIid,
+                logStep,
+            })
+            : answer;
         logStep("Posting AI review note to merge request");
         const noteRes = await postMergeRequestNote({
             gitLabProjectApiUrl: gitLabProjectApiUrl,
             headers,
             mergeRequestIid,
-            note: answer,
+            note,
         });
         if (noteRes instanceof Error)
             throw noteRes;

package/dist/gitlab/services.js

@@ -39,6 +39,13 @@ export const fetchFileAtRef = async ({ gitLabProjectApiUrl, headers, filePath, r
     }
     return await res.text();
 };
+/** GitLab runs quick actions (`/merge`, `/approve`, …) that start a line of a
+ *  note, with the token's permissions. Model text must never trigger them, so
+ *  indent such lines by a space (renders the same, no longer a command).
+ *  Command names start with a letter, so `// comment` lines stay as they are. */
+function neutralizeQuickActions(body) {
+    return body.replace(/^\/(?=[a-z])/gim, " /");
+}
 export const postMergeRequestNote = async ({ gitLabProjectApiUrl, headers, mergeRequestIid, note }) => {
     const commentUrl = new URL(`${gitLabProjectApiUrl}/merge_requests/${mergeRequestIid}/notes`);
     let aiComment;
@@ -49,7 +56,7 @@ export const postMergeRequestNote = async ({ gitLabProjectApiUrl, headers, merge
                 ...headers,
                 "Content-Type": "application/json",
             },
-            body: JSON.stringify({ body: note }),
+            body: JSON.stringify({ body: neutralizeQuickActions(note) }),
         });
     }
     catch (error) {
@@ -162,3 +169,78 @@ export const fetchMergeRequestChanges = async ({ gitLabProjectApiUrl, headers, m
     }
     return (await res.json());
 };
+/** fetch with the same error details as above, for the inline-comment calls. */
+async function gitlabRequest(url, init, message) {
+    let res;
+    try {
+        res = await fetch(url, init);
+    }
+    catch (error) {
+        res = error;
+    }
+    if (!(res instanceof Error) && res.ok)
+        return res;
+    const cause = res instanceof Error
+        ? { url: url.toString(), error: { name: res.name, message: res.message } }
+        : {
+            url: url.toString(),
+            status: res.status,
+            statusText: res.statusText,
+            body: (await res.text().catch(() => "")).slice(0, 1000),
+        };
+    return new GitLabError({
+        name: "INLINE_COMMENTS_FAILED",
+        message,
+        statusCode: res instanceof Error ? 502 : res.status,
+        cause,
+    });
+}
+export const fetchMergeRequestDiffRefs = async ({ gitLabProjectApiUrl, headers, mergeRequestIid }) => {
+    const res = await gitlabRequest(new URL(`${gitLabProjectApiUrl}/merge_requests/${mergeRequestIid}`), { headers: { ...headers } }, "Failed to fetch merge request");
+    if (res instanceof Error)
+        return res;
+    const mr = (await res.json());
+    return mr.diff_refs ?? {};
+};
+export const listMergeRequestDiscussions = async ({ gitLabProjectApiUrl, headers, mergeRequestIid }) => {
+    const discussions = [];
+    // ponytail: reads at most 50 pages (5000 threads); raise if an MR ever has more.
+    for (let page = 1; page <= 50; page += 1) {
+        const url = new URL(`${gitLabProjectApiUrl}/merge_requests/${mergeRequestIid}/discussions`);
+        url.searchParams.set("per_page", "100");
+        url.searchParams.set("page", String(page));
+        const res = await gitlabRequest(url, { headers: { ...headers } }, "Failed to list merge request threads");
+        if (res instanceof Error)
+            return res;
+        const batch = (await res.json());
+        discussions.push(...batch);
+        // A page can be short while more follow (GitLab drops notes the token
+        // can't read after paginating), so trust X-Next-Page when it is sent.
+        const next = res.headers.get("x-next-page");
+        if (next === "" || (next == null && batch.length < 100))
+            break;
+    }
+    return discussions;
+};
+export const createMergeRequestDiscussion = async ({ gitLabProjectApiUrl, headers, mergeRequestIid, body, position }) => {
+    const res = await gitlabRequest(new URL(`${gitLabProjectApiUrl}/merge_requests/${mergeRequestIid}/discussions`), {
+        method: "POST",
+        headers: { ...headers, "Content-Type": "application/json" },
+        body: JSON.stringify({ body: neutralizeQuickActions(body), position }),
+    }, `Failed to create a diff thread at ${position.new_path}:${position.new_line}`);
+    return res instanceof Error ? res : undefined;
+};
+export const resolveMergeRequestDiscussion = async ({ gitLabProjectApiUrl, headers, mergeRequestIid, discussionId }) => {
+    const url = new URL(`${gitLabProjectApiUrl}/merge_requests/${mergeRequestIid}/discussions/${discussionId}`);
+    url.searchParams.set("resolved", "true");
+    const res = await gitlabRequest(url, { method: "PUT", headers: { ...headers } }, `Failed to resolve thread ${discussionId}`);
+    return res instanceof Error ? res : undefined;
+};
+export const replyToMergeRequestDiscussion = async ({ gitLabProjectApiUrl, headers, mergeRequestIid, discussionId, body }) => {
+    const res = await gitlabRequest(new URL(`${gitLabProjectApiUrl}/merge_requests/${mergeRequestIid}/discussions/${discussionId}/notes`), {
+        method: "POST",
+        headers: { ...headers, "Content-Type": "application/json" },
+        body: JSON.stringify({ body: neutralizeQuickActions(body) }),
+    }, `Failed to reply to thread ${discussionId}`);
+    return res instanceof Error ? res : undefined;
+};

package/dist/prompt/index.js

@@ -1,6 +1,6 @@
 /** @format */
 import { buildFileReviewSystemMessage, buildMainSystemMessages, buildTriageSystemMessage, } from "./messages.js";
-import { extractFirstJsonObject, normalizeReviewFindingsMarkdown, sanitizeGitLabMarkdown, truncateWithMarker, } from "./utils.js";
+import { extractFirstJsonObject, normalizeReviewFindingsMarkdown, numberDiffLines, sanitizeGitLabMarkdown, truncateWithMarker, } from "./utils.js";
 import { getConsolidateSystemPrompt, getVerificationSystemPrompt, } from "./templates/postprocess-system.js";
 import { buildConsolidateUserContent, buildFileReviewUserContent, buildMainReviewUserContent, buildTriageUserContent, buildVerificationUserContent, } from "./templates/user-prompts.js";
 import { DEFAULT_PROMPT_PROFILE, isEmptyReviewBody } from "./profile.js";
@@ -21,10 +21,11 @@ export const buildPrompt = ({ changes, limits, allowTools = false, profile = DEF
     const capped = changes.slice(0, effectiveLimits.maxDiffs);
     const omittedFiles = totalFiles - capped.length;
     let truncatedCount = 0;
-    const diffsTrimmed = capped.map((change, index) => {
+    const diffsTrimmed = capped.map((change) => {
         if (change.diff.length > effectiveLimits.maxDiffChars)
             truncatedCount += 1;
-        return truncateWithMarker(change.diff, effectiveLimits.maxDiffChars, `diff #${index + 1}`);
+        // GitLab's per-file diff starts at the first @@ line, without a file header.
+        return `### ${change.path}\n${numberDiffLines(truncateWithMarker(change.diff, effectiveLimits.maxDiffChars, change.path))}`;
     });
     const changesText = diffsTrimmed.join("\n\n");
     const statsFragments = [`${capped.length} file diff(s) included.`];
@@ -139,7 +140,7 @@ export function buildFileReviewPrompt(params) {
             role: "user",
             content: buildFileReviewUserContent({
                 filePath,
-                fileDiff,
+                fileDiff: numberDiffLines(fileDiff),
                 summary,
                 otherChangedFiles,
                 toolNote,
@@ -217,7 +218,7 @@ export function extractCompletionText(completion) {
     return null;
 }
 const ERROR_ANSWER = "AI review could not be completed. Please ask a human to review this code change.";
-const DISCLAIMER = "This comment was generated by AI review bot.";
+export const DISCLAIMER = "This comment was generated by AI review bot.";
 export const buildAnswer = (completion) => {
     if (completion instanceof Error) {
         const maybeCause = completion.cause;

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

@@ -51,6 +51,7 @@ Your job is to remove weak, speculative, or unsupported findings from the draft
 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.
+get_file_at_ref numbers every line: when it shows the offending code on a different line than cited, set Line: to that number.
 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:
@@ -70,7 +71,7 @@ Return at most ${maxFindings} findings.
 
 For each draft finding, follow these steps in order:
 1. Look it up in the per-file evidence pool. If it is not in the evidence pool, drop it.
-2. If the finding makes a claim about code that exists at refs.head, call get_file_at_ref(path, refs.head) and confirm the offending text really sits at the cited line (±10 lines is fine).
+2. If the finding makes a claim about code that exists at refs.head, call get_file_at_ref(path, refs.head) and confirm the offending text really sits at the cited line (±10 lines is fine). Each line of its output starts with the line number; set Line: to the number of the offending line.
 3. If the file contents at refs.head do not contain the offending text, or contain a corrected version of it, drop the finding.
 4. If you cannot confirm the claim with one or two tool calls, drop the finding.
 

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

@@ -1,8 +1,10 @@
 /** @format */
 import { truncateWithMarker } from "../utils.js";
+const LINE_NUMBERS_NOTE = "Each diff line starts with its line number in the new file (removed lines have none); use these numbers for Line:.";
 export function buildMainReviewUserContent(params) {
     const { stats, toolNote, changesText } = params;
     return `Review the following code changes (git diff format). ${stats}
+${LINE_NUMBERS_NOTE}
 ${toolNote}
 
 Changes:
@@ -36,6 +38,7 @@ ${otherFilesNote}
 ${toolNote}
 
 File: ${filePath}
+${LINE_NUMBERS_NOTE}
 Diff:
 ${fileDiff}
 

package/dist/prompt/utils.js

@@ -47,6 +47,28 @@ export function truncateWithMarker(value, maxChars, markerLabel) {
     const omitted = value.length - maxChars;
     return `${value.slice(0, maxChars)}\n\n[... ${markerLabel} truncated, omitted ${omitted} chars ...]`;
 }
+/** Prefixes added and context lines of a unified diff with their line number in
+ *  the new file (removed lines get a blank column), so the model cites exact
+ *  lines instead of counting from @@ headers. Same rules as mapNewLines. */
+export function numberDiffLines(diff) {
+    const rows = [];
+    let newLine = 0;
+    for (const text of diff.split("\n")) {
+        const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(text);
+        if (hunk != null)
+            newLine = Number(hunk[1]);
+        const numbered = hunk == null && newLine > 0 && /^[+ ]/.test(text);
+        rows.push([numbered ? newLine++ : null, text]);
+    }
+    const width = String(Math.max(1, newLine - 1)).length;
+    return rows
+        .map(([n, text]) => n != null
+        ? `${String(n).padStart(width)} ${text}`
+        : text.startsWith("-")
+            ? `${" ".repeat(width)} ${text}`
+            : text)
+        .join("\n");
+}
 export function sanitizeGitLabMarkdown(input) {
     const normalized = input.replace(/\r\n/g, "\n").trim();
     // If the model forgets to close a fenced code block, GitLab will render the rest (incl. disclaimer) inside it.
@@ -97,6 +119,18 @@ export function parseReviewFindings(input) {
                 if (m != null) {
                     file = m[1].trim();
                     line = m[2].trim();
+                    // renderReviewFinding puts the why on the very next line, even when
+                    // it starts with `_` (e.g. `__init__`), which the fallback below skips.
+                    // Separators and whole-line italics (the disclaimer) are never a why.
+                    const next = lines[j + 1]?.trim() ?? "";
+                    if (why == null &&
+                        next !== "" &&
+                        !/^(-{3,}|_.*_$)/.test(next) &&
+                        matchHeader(next) == null) {
+                        why = next.match(whyRe)?.[1]?.trim() ?? next;
+                        j += 2;
+                        continue;
+                    }
                     j += 1;
                     continue;
                 }
@@ -143,6 +177,14 @@ export function parseReviewFindings(input) {
     }
     return findings;
 }
+const SEVERITY_LABEL = {
+    high: "🔴 High",
+    medium: "🟠 Medium",
+};
+/** One finding as rendered in the MR comment (and in inline diff threads). */
+export function renderReviewFinding(f) {
+    return `- **${SEVERITY_LABEL[f.severity]} — ${f.title}**  \n  \`${f.file}:${f.line}\`  \n  ${f.why}`;
+}
 export function normalizeReviewFindingsMarkdown(input) {
     const normalized = input.replace(/\r\n/g, "\n").trim();
     if (normalized === "" || normalized === NO_ISSUES_SENTENCE)
@@ -150,11 +192,5 @@ export function normalizeReviewFindingsMarkdown(input) {
     const findings = parseReviewFindings(normalized);
     if (findings.length === 0)
         return normalized;
-    const severityLabel = {
-        high: "🔴 High",
-        medium: "🟠 Medium",
-    };
-    return findings
-        .map((f) => `- **${severityLabel[f.severity]} — ${f.title}**  \n  \`${f.file}:${f.line}\`  \n  ${f.why}`)
-        .join("\n\n");
+    return findings.map(renderReviewFinding).join("\n\n");
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@krotovm/gitlab-ai-review",
-  "version": "1.0.43",
+  "version": "1.0.44",
   "description": "CLI tool to generate AI code reviews for GitLab merge requests.",
   "main": "dist/cli.js",
   "bin": {
@@ -16,7 +16,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "prepare": "tsc"
+    "prepare": "tsc",
+    "test": "tsc && node --test"
   },
   "keywords": [
     "gitlab",