Key APIs Exposed by Open-Code-Review: CLI, Library, and HTTP Viewer

Open-Code-Review exposes three distinct API layers—a Cobra-based CLI for terminal operations, reusable Go packages for programmatic integration, and an HTTP viewer for web-based session inspection.

The Alibaba Open-Code-Review project is a Go-based code review automation tool that structures its functionality across multiple public interfaces. Understanding the key APIs exposed by Open-Code-Review enables developers to automate code scanning in CI pipelines, embed review logic into custom applications, or inspect historical sessions through a web interface.

CLI Command API

The cmd/opencodereview package implements the primary user-facing interface using the Cobra library. In cmd/opencodereview/main.go, the root command wires together sub-commands and handles global flags such as --config and --verbose.

The scan Sub-command

The scan command walks a repository, builds a diff tree, and sends it to an LLM for static analysis. The entry point is the runScanCmd function defined in cmd/opencodereview/scan_cmd.go.

// Simplified conceptual usage
opencodereview scan --config ./config.yaml ./repository-path

The review Sub-command

The review command generates detailed code-review reports for specific diffs or commit ranges. This is implemented in cmd/opencodereview/review_cmd.go via the runReviewCmd function.

Additional CLI Commands

Three additional sub-commands complete the CLI surface:

• provider (cmd/opencodereview/provider_cmd.go, runProviderCmd): Configures and invokes CI-specific providers (GitLab, Gerrit, etc.) that supply patches to the review pipeline.
• session (cmd/opencodereview/session_cmd.go, runSessionCmd): Lists, shows, or deletes stored review sessions from local storage.
• viewer (cmd/opencodereview/viewer_cmd.go, runViewerCmd): Launches a read-only HTTP server that visualizes stored sessions.

Core Library API

The core library API consists of reusable Go packages under internal/ that implement the tool's business logic. These packages expose exported functions and types that the CLI commands consume, allowing programmatic use independent of the terminal interface.

Model Types (internal/model)

The internal/model package defines structured representations of review operations in scan.go, review.go, and preview.go:

• type Scan: Encapsulates a scanning run, including metadata and diff context.
• type Review: Contains LLM-generated suggestions and review metadata.
• type Preview: Represents preview data for review sessions.

import "github.com/alibaba/open-code-review/internal/model"

// Create a Scan model from repository diff data
scan, err := model.NewScan(diffBytes)

Diff Processing (internal/diff)

The internal/diff package provides low-level diff parsing and normalization through parser.go, resolver.go, and relocation.go:

• ResolveDiff: Parses raw diff bytes into structured hunks.
• ParseDiff: Handles initial diff parsing logic.
• RelocateHunk: Adjusts hunk positions after modifications.

import "github.com/alibaba/open-code-review/internal/diff"

// Resolve a diff into structured hunks
hunks, err := diff.Resolve(diffBytes)

LLM Orchestration (internal/llm)

The internal/llm package abstracts multiple LLM providers (OpenAI, Azure, etc.) through files like resolver.go and client.go:

• Resolver: Orchestrates LLM requests and response handling.
• Client: Manages HTTP connections to LLM endpoints.
• Message: Structures request/response payloads.
• UsageResolver: Tracks token consumption and API usage.

The internal/llmloop package extends this with Loop and Pool types (loop.go, pool.go) for managing multi-turn conversations, retries, and streaming responses.

import "github.com/alibaba/open-code-review/internal/llm"

// Send a prompt to an LLM and receive structured suggestions
resolver := llm.NewResolver(cfg)
resp, err := resolver.Run(ctx, prompt)

CI Provider Integration (internal/mcp)

The internal/mcp package defines the Provider interface in provider.go, with concrete implementations for GitLab, Gerrit, and CodeUp. This abstraction allows the core pipeline to fetch merge request diffs from various CI systems uniformly.

import (
    "github.com/alibaba/open-code-review/internal/mcp"
    "github.com/alibaba/open-code-review/internal/mcp/provider"
)

// Fetch a GitLab MR diff
prov := provider.NewGitLabProvider(token, endpoint)
diffBytes, err := prov.FetchDiff(ctx, projectID, mrIID)

HTTP Viewer API

The HTTP viewer API exposes a lightweight web interface for exploring stored review sessions. Defined primarily in internal/viewer/server.go and internal/viewer/store.go, this layer provides REST-like endpoints consumed by a static HTML/JS frontend.

Key functions include:

• viewer.StartServer(addr string) error (server.go): Starts the HTTP listener on the specified address.
• viewer.DiscoverRepos(root string) ([]RepoInfo, error) (store.go): Enumerates repositories containing stored sessions.
• viewer.ListSessions(root, encodedRepo string) ([]SessionSummary, error) (store.go): Returns session summaries for a specific repository.
• viewer.LoadSession(root, encodedRepo, sessionID string) (*ViewSession, error) (store.go): Retrieves a complete session including the LLM transcript.

The handlers in internal/viewer/handler.go (handleRepos, handleSessions, handleSession) serve JSON responses at paths like /repos, /sessions, and /session/:id.

import "github.com/alibaba/open-code-review/internal/viewer"

// Start the viewer on localhost:8080
err := viewer.StartServer("127.0.0.1:8080")

Summary

• CLI Layer: Five sub-commands (scan, review, provider, session, viewer) implemented in cmd/opencodereview/ provide the primary terminal interface.
• Library Layer: Go packages under internal/model, internal/diff, internal/llm, and internal/mcp expose programmatic APIs for embedding scan and review logic.
• Viewer Layer: Functions like StartServer, DiscoverRepos, and LoadSession in internal/viewer/ enable web-based session inspection.
• Integration Points: The Provider interface abstracts CI systems, while the Resolver types handle LLM orchestration across multiple providers.

Frequently Asked Questions

What is the entry point for running a code scan programmatically?

The internal/model package provides the entry point through model.NewScan(), which accepts diff bytes and returns a structured Scan type. You then use llm.NewResolver() to apply LLM analysis to the scan object, as implemented in internal/model/scan.go and internal/llm/resolver.go.

Can I use Open-Code-Review as a library in my own Go application?

Yes. While the packages reside under internal/, they expose exported functions and types that you can import directly. The core workflow involves calling diff.Resolve() to parse diffs, creating models via model.NewScan(), and invoking llm.Resolver.Run() to generate reviews, effectively bypassing the CLI layer.

How does the HTTP viewer retrieve stored session data?

The viewer uses functions defined in internal/viewer/store.go. DiscoverRepos() locates repositories with stored data, ListSessions() provides summaries for a specific repo, and LoadSession() fetches the complete session details including the LLM conversation transcript. These are served via HTTP handlers in internal/viewer/handler.go.

Which file handles the CLI command routing?

Command routing and global flag handling occur in cmd/opencodereview/main.go. This file initializes the Cobra root command and registers sub-command implementations from scan_cmd.go, review_cmd.go, provider_cmd.go, session_cmd.go, and viewer_cmd.go.

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