Comment Positioning Module Explained: How Alibaba Open Code Review Achieves Precise AI Comment Placement

The comment positioning module in Alibaba Open Code Review parses LLM-generated feedback, extracts exact file paths and line/column coordinates, and maps each comment to its precise source location—eliminating misalignment and improving placement accuracy by approximately 30%.

Open Code Review (OCR) by Alibaba automates AI-powered code reviews using large language models. A critical challenge in LLM-driven code review is ensuring generated comments appear at the correct locations in source files. The comment positioning module solves this by bridging the gap between unstructured LLM output and deterministic, line-accurate comment placement.

How the Comment Positioning Module Works

The module operates across four core components that transform raw LLM responses into precisely positioned review comments.

1. Parsing LLM Output with internal/tool/code_comment.go

The entry point is ParseComments in internal/tool/code_comment.go. This function validates and extracts structured data from the LLM's JSON payload.

{
  "path": "src/main.go",
  "line": 42,
  "column": 5,
  "content": "Consider using a buffered writer here",
  "severity": "high"
}

If line or column are missing, the parser falls back to character-wise token offsets computed from the file's token stream. This ensures robust positioning even when the LLM provides incomplete coordinate data.

2. Modeling Comments in internal/model/review.go

Parsed data becomes model.LlmComment objects defined in internal/model/review.go. The core ReviewComment struct stores:

• path — absolute or relative file path
• line — 1-based line number
• column — optional 1-based column offset
• position — fallback character offset for diff-based placement

// Conceptual structure based on module design
type ReviewComment struct {
    Path    string
    Line    int
    Column  int
    Content string
}

3. Collecting and Deduplicating with CommentCollector

The CommentCollector type provides position-aware operations:

• AddComment(c LlmComment) — inserts a comment into the collection
• ReplaceSince(timestamp, comments []LlmComment) — atomically replaces outdated comments while preserving positions of unchanged feedback
• CommentsForPath(path string) — returns comments sorted by line/column for deterministic rendering

This deduplication prevents comment drift across multiple review iterations.

4. Rendering in internal/viewer/store.go and internal/viewer/server.go

The viewer layer consumes positioned comments via:

File	Function	Purpose
internal/viewer/store.go	store.AddComment()	Updates the "comment-by-file" map using position data
internal/viewer/server.go	groupCommentsByFile()	Groups comments by file and sorts by line/column
UI templates	Position calculation	Computes DOM offsets from line numbers for overlay rendering

Accuracy Benefits of Comment Positioning

The positioning module delivers measurable improvements across five dimensions:

• Exact Line Placement — Reviewers see comments adjacent to target code, eliminating the "guesswork" common in file-level-only grouping systems.

• Misalignment Prevention — Token-offset fallback handling stops comments from drifting to unrelated lines when LLM output varies.

• Deterministic Rendering — Consistent line/column sorting guarantees identical UI layouts across repeated runs, critical for CI/CD integration.

• Multi-Turn Coherence — When exact positions feed back into the LLM context, subsequent review rounds can reference previous comments for more coherent suggestions.

• Accelerated Developer Workflow — Precise positioning enables one-click fix application, reducing review cycle time.

Benchmark data included in the repository (imgs/benchmark-en.png) demonstrates approximately 30% improvement in "percentage of comments placed on the exact intended line" compared to baseline file-level placement.

Practical Usage Examples

Running a Positioned Review from CLI

# Execute OCR on a repository

opencodereview review --path ./my-go-app

# Browser opens with comments rendered at precise line locations

# Example: A suggestion for src/main.go:42 appears directly beside line 42

Programmatic Positioning API

package main

import (
    "fmt"
    "github.com/alibaba/open-code-review/internal/tool"
)

func main() {
    // Simulate LLM-generated payload
    payload := map[string]any{
        "path":    "src/main.go",
        "line":    42,
        "column":  5,
        "content": "Consider using a buffered writer here.",
    }

    // Parse into structured comments
    comments, err := tool.ParseComments(payload)
    if err != nil {
        panic(err)
    }

    // Collect with position-aware storage
    collector := tool.NewCommentCollector()
    for _, c := range comments {
        collector.AddComment(c)
    }

    // Retrieve sorted comments for specific file
    fileComments := collector.CommentsForPath("src/main.go")
    for _, c := range fileComments {
        fmt.Printf("Line %d: %s\n", c.Line, c.Content)
    }
}

Key Source Files

File	Responsibility
internal/tool/code_comment.go	Parses LLM JSON into model.LlmComment with fallback offset calculation
internal/model/review.go	Defines ReviewComment struct with path/line/column/position fields
internal/viewer/store.go	Position-aware in-memory storage and lookup
internal/viewer/server.go	Groups and sorts comments by position for UI rendering
imgs/benchmark-en.png	Visual accuracy benchmark showing ~30% placement improvement

Summary

• The comment positioning module transforms unstructured LLM output into precisely located review comments through parsing, modeling, collection, and rendering stages.

• Four components handle the pipeline: code_comment.go for parsing, review.go for data modeling, CommentCollector for deduplication, and the viewer layer for visualization.

• Token-offset fallback ensures robust positioning when the LLM omits explicit coordinates.

• Deterministic sorting by line and column guarantees consistent, repeatable UI layouts.

• Benchmark evidence shows ~30% accuracy improvement over file-level placement approaches.

Frequently Asked Questions

What happens when the LLM doesn't provide line numbers?

The positioning module falls back to character-wise token offsets computed from the file's token stream. This secondary coordinate system maps comments to approximate positions even without explicit line data, preventing complete misplacement.

How does comment deduplication preserve positioning?

CommentCollector.ReplaceSince() performs atomic batch replacement: it identifies comments by their generation timestamp, removes outdated entries, and inserts new ones while retaining positions of unchanged feedback. This prevents "comment jumping" between review iterations.

Can I use the positioning module outside the full OCR pipeline?

Yes. The internal/tool package exposes ParseComments() and CommentCollector as a standalone API. Import github.com/alibaba/open-code-review/internal/tool to integrate precise comment positioning into custom code review tools or CI scripts.

Why does sorting by line and column matter for CI/CD?

Deterministic ordering ensures that repeated runs produce identical comment layouts. This stability is essential for automated checks that compare review outputs across builds, and for caching strategies that avoid redundant LLM calls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}