gitlab-ai-code-review: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Niteni is an AI-powered code review tool for GitLab CI pipelines, powered by Google's Gemini API. The name comes from Javanese, meaning "to observe carefully." It posts inline diff comments with suggestions directly on GitLab merge requests.

Zero external runtime dependencies — only uses Node.js built-in modules (https, child_process, fs, path, os, url) plus TypeScript for compilation.

Commands

npm run build              # Compile TypeScript (tsc)
npm run dev                # Watch mode compilation
npm run lint               # ESLint on src/
npm run test               # Node built-in test runner (dist/**/*.test.js) — build first
npm run review:simulate    # Run simulation mode with mock data (needs ts-node)
npm run simulate           # Run simulation from compiled output

Tests use Node's built-in node:test and node:assert modules. Run npm run build && npm test to compile and execute tests from dist/**/*.test.js.

Architecture

src/
├── cli.ts          # CLI entry point — three modes: mr, diff, simulate
├── index.ts        # Main orchestration: runMergeRequestReview() & runDiffReview()
├── reviewer.ts     # Gemini review logic with structured JSON output
├── gitlab-api.ts   # GitLab REST API client (MR data, inline comments, cleanup)
├── config.ts       # Environment variable parsing & validation
├── simulate.ts     # Self-contained demo with ANSI-colored mock output
└── types/
    ├── index.ts    # Barrel export
    ├── config.ts   # AppConfig, GitLabConfig, GeminiConfig, ReviewConfig
    ├── gitlab.ts   # MergeRequest, DiffPosition, MergeRequestNote
    └── reviewer.ts # Severity, Finding, StructuredReviewResponse, ReviewResult, FilterOptions

Gemini Structured Output (reviewer.ts)

The Reviewer class uses the Gemini REST API with structured output (responseMimeType: "application/json" + responseSchema) to return typed StructuredReviewResponse objects directly — no regex parsing needed. The response schema enforces summary (string) and findings (array of Finding objects with severity, file, line, description, optional suggestion/rationale).