Cách thực hiện đánh giá Git và cơ sở mã có cấu trúc với Jev Review

Jev Review thực hiện những gì

Jev Review là một quy trình review mã nguồn nhỏ được xây dựng bằng TypeSafe Jev. Công cụ có thể review Git diff hoặc quét mọi tệp mã nguồn không bị bỏ qua trong phạm vi đã chọn, sau đó hiển thị các phát hiện trên một dashboard cục bộ, tối giản.

Quy trình giữ phần điều phối và chính sách trong mã ứng dụng, đồng thời sử dụng Jev cho các đánh giá có giới hạn và cấu trúc rõ ràng. Các phát hiện nhằm cung cấp gợi ý review, không phải bằng chứng chắc chắn rằng lỗi thực sự tồn tại.

Quy trình review hoạt động như thế nào

Jev Review thực hiện theo quy trình nhiều giai đoạn, được thiết kế để thu hẹp phạm vi chú ý trước khi xác định mức độ ảnh hưởng:

1. Xây dựng ma trận rủi ro.
2. Chọn và chấm điểm hồ sơ tệp.
3. Chọn bằng chứng liên quan.
4. Phân loại cơ chế nền tảng.
5. Chấm mức độ nghiêm trọng.
6. Chuyển các phát hiện đã chọn cho reviewer khi quy trình yêu cầu.

Reviewer kiểm tra tính chính xác, bảo mật, độ tin cậy, khả năng tương thích và độ bao phủ kiểm thử. Khi đánh giá các thiếu sót trong kiểm thử, công cụ có thể sử dụng các kiểm thử đã thay đổi hoặc liên quan làm ngữ cảnh. Công cụ cũng chọn các hunk cụ thể trong diff hoặc vùng mã nguồn trước khi chấm mức độ ảnh hưởng, đồng thời áp dụng các gợi ý có cấu trúc, phản ví dụ, ranh giới quyết định, ngưỡng và chính sách quy trình.

Điều kiện tiên quyết và cài đặt

Trước khi bắt đầu, hãy cài đặt Node.js 24 trở lên và Git. Bạn cũng cần một API key TypeSafe.

Clone hoặc lấy dự án theo cách khác, sau đó cài đặt các dependency:

npm install

Tạo tệp môi trường từ tệp mẫu được cung cấp:

cp .env.example .env

Mở .env và thêm API key của bạn:

TYPESAFE_API_KEY=your_api_key

Không cung cấp tệp này thông qua dashboard. Jev Review liên kết dashboard với 127.0.0.1 và không phục vụ các tệp môi trường.

Review Git Diff hiện tại

Để in kết quả review Git diff hiện tại dưới dạng JSON, hãy chạy lệnh review thay đổi và cung cấp đường dẫn đến một Git repository:

npm run review:changes -- /path/to/git/repository

Chế độ này hữu ích khi bạn muốn nhận phản hồi tập trung vào những thay đổi hiện có trong repository.

Để lưu kết quả và xem sau trong dashboard, hãy sử dụng biến thể lưu:

npm run review:changes:save -- /path/to/git/repository

Quét toàn bộ codebase

Để review trên phạm vi rộng hơn, hãy quét mọi tệp mã nguồn không bị bỏ qua trong repository hoặc phạm vi package:

npm run review:codebase -- /path/to/git/repository-or-package

Lệnh này in kết quả quét toàn bộ codebase dưới dạng JSON. Để thay vào đó lưu báo cáo cho dashboard, hãy chạy:

npm run review:codebase:save -- /path/to/git/repository-or-package

Hãy dùng điểm vào review thay đổi khi cần review tập trung các sửa đổi đang hoạt động, và dùng điểm vào review toàn bộ codebase khi muốn kiểm tra các tệp mã nguồn hiện có trong một phạm vi đã chọn.

Mở dashboard cục bộ

Sau khi lưu một bản review thay đổi hoặc bản quét codebase, hãy khởi động dashboard cục bộ:

npm run dashboard

Mở http://127.0.0.1:4317 trong trình duyệt. Các báo cáo lớn được hiển thị trong những phần có thể thu gọn, giúp điều hướng qua các phát hiện dễ dàng hơn mà không cần rời khỏi môi trường cục bộ.

Tham khảo lệnh

• npm run review:changes -- <path> in kết quả review diff hiện tại dưới dạng JSON.
• npm run review:changes:save -- <path> lưu kết quả review diff hiện tại cho dashboard.
• npm run review:codebase -- <path> in kết quả quét toàn bộ codebase dưới dạng JSON.
• npm run review:codebase:save -- <path> lưu kết quả quét toàn bộ codebase cho dashboard.
• npm run dashboard khởi động dashboard cục bộ.
• npm run check kiểm tra kiểu cho dự án, xác minh luồng dependency và kiểm tra cú pháp client dashboard.

Tìm hiểu cấu trúc dự án

Phần triển khai được tổ chức dưới src/ theo các lớp chỉ phụ thuộc vào những lớp thấp hơn:

src/
  domain/      config.ts, types.ts, patch.ts
  adapters/    git.ts, repository-files.ts
               report-store.ts
  review/      changes.ts, codebase.ts
               *-judgments.ts, workflow.ts
  cli/         review-*.ts, save-*.ts
  dashboard/   server.ts, public/

Các lớp có trách nhiệm như sau:

• Domain: cấu hình dùng chung, kiểu báo cáo, chính sách và phân tích diff.
• Adapters: phát hiện Git và mã nguồn đầy đủ, cùng với việc lưu và tải báo cáo nguyên tử.
• Review: quy trình theo từng chế độ, các lệnh gọi Jev và điều phối theo giai đoạn.
• CLI: các điểm vào review và lưu rõ ràng.
• Dashboard: máy chủ HTTP chỉ chạy cục bộ và client thuần.

Luồng import đi từ cli và dashboard xuống review, rồi đến adapters và domain. Các lớp dashboard và CLI không import lẫn nhau.

Sử dụng nâng cao và kiểm tra dự án

Hãy chạy các bước kiểm tra dự án trước khi dựa vào một thay đổi trong quy trình hoặc đóng góp một sửa đổi về kiến trúc:

npm run check

Lệnh này kiểm tra kiểu, xác minh luồng phụ thuộc và kiểm tra cú pháp của ứng dụng dashboard. Tập lệnh phụ thuộc sẽ thất bại khi phát hiện các import hướng lên, import giữa cli và dashboard hoặc các chu kỳ phụ thuộc.

Để đánh giá tập trung hơn, hãy lưu báo cáo thay đổi sau khi thực hiện các thay đổi Git liên quan và kiểm tra báo cáo qua dashboard. Để điều tra phạm vi rộng hơn, hãy cung cấp đường dẫn đến kho lưu trữ hoặc phạm vi gói mà bạn muốn quét. Hai điểm vào này tách biệt các quy trình làm việc theo thay đổi và trên toàn bộ mã nguồn.

Hãy nhớ rằng Jev Review là một thử nghiệm về việc kết hợp các nhận định nhanh có kiểu dữ liệu. Hiện tại, công cụ này chưa tích hợp chẩn đoán trình biên dịch, trình phân tích tĩnh, lập chỉ mục kho lưu trữ hoặc phần giải thích được tạo tự động. Hãy xem các phát hiện của công cụ như gợi ý để con người đánh giá, đặc biệt trước khi thực hiện thay đổi chỉ dựa trên mức độ nghiêm trọng được báo cáo.

Kết luận

Jev Review cung cấp hai chế độ đánh giá thực tế: phân tích tập trung phần khác biệt Git hiện tại và quét toàn bộ phạm vi mã nguồn không bị bỏ qua. Hãy cài đặt các phần phụ thuộc, cấu hình TYPESAFE_API_KEY, lưu báo cáo và mở dashboard cục bộ để kiểm tra các phát hiện có cấu trúc. Các nhận định theo từng giai đoạn, việc lựa chọn bằng chứng và chính sách quy trình rõ ràng khiến công cụ trở thành một thử nghiệm cục bộ hữu ích để tổ chức hoạt động đánh giá mã nguồn có AI hỗ trợ.