Tôi đã hủy dịch vụ review mã AI trả phí và tự viết công cụ miễn phí chạy cục bộ

Một nhà phát triển đã chia sẻ hành trình từ bỏ dịch vụ review mã AI trả phí để tự xây dựng Avouch — một công cụ phân tích tĩnh mã Python nhẹ, nhận biết Git và chạy hoàn toàn cục bộ. Avouch chỉ tập trung review những tệp bạn sắp commit, sử dụng AST (Abstract Syntax Tree) để đưa ra các phép đo chính xác mà không cần kết nối mạng hay daemon. Công cụ mã nguồn mở này hiện đã có trên GitHub với 17 quy tắc kiểm tra, hỗ trợ tích hợp CI và hoàn toàn miễn phí.

Vì sao Avouch ra đời?

Vấn đề lớn nhất mà tác giả gặp phải với các dịch vụ review mã AI là chi phí và sự phức tạp không cần thiết. Thay vì trả phí hàng tháng cho một dịch vụ đám mây, anh quyết định viết một công cụ đơn giản hơn nhưng hiệu quả hơn cho nhu cầu cụ thể: review những gì bạn sắp push, không phải toàn bộ codebase.

"Review set là diff, không phải repository. Avouch tính toán review set từ Git tại thời điểm chạy — mọi phát hiện đều thuộc về công việc bạn sắp push, không bao giờ là code legacy kế thừa."

Điểm mấu chốt của triết lý này: tránh nhiễu từ những vấn đề tồn tại sẵn trong dự án, chỉ tập trung vào thay đổi mới.

Tính năng nổi bật

Chính xác tuyệt đối nhờ AST

Avouch không sử dụng regex như nhiều công cụ khác. Mọi số liệu — số tham số, độ sâu lồng nhau, độ dài dòng — đều được tính từ AST, đảm bảo độ chính xác cho mọi tệp Python hợp lệ.

Chạy cục bộ, không cần mạng

Chỉ cần Python 3.10+ và Git. Không daemon, không kết nối mạng, thời gian chạy tỷ lệ với kích thước diff chứ không phải toàn bộ repository.

Báo cáo dạng dữ liệu

Avouch xuất ra JSON ổn định với phiên bản schema, phù hợp cho tự động hóa và CI. Nó không chỉ "gate" mà còn cung cấp đầy đủ thông tin để phản hồi.

Cài đặt và sử dụng

Cài đặt cực kỳ đơn giản:

pip install avouch
cd your-repo
avouch

Các tùy chọn chính:

• --json — xuất kết quả dạng JSON
• --changed, --staged, --all-files — chọn phạm vi review
• --quiet — chỉ trả về mã thoát, không in báo cáo
• --not-git — review mọi tệp .py trong thư mục, không cần Git

17 quy tắc kiểm tra

Avouch cung cấp 17 quy tắc (SCR001–SCR017) bao phủ nhiều vấn đề phổ biến:

• SCR002 — Bắt exception quá rộng (except: không chỉ định loại)
• SCR014 — Quá nhiều tham số (mặc định >5)
• SCR017 — Tham số mặc định có giá trị mutable (như [] hoặc {})
• SCR015 — Hàm lồng nhau không cần thiết
• SCR016 — Quá nhiều câu lệnh return
• SCR013 — Độ sâu lồng nhau quá lớn

Ngoài ra còn có kiểm tra cyclomatic complexity cho hàm và class, đo mức độ phức tạp logic.

Tích hợp CI/CD

Avouch có thể chạy trong GitHub Actions hoặc bất kỳ CI nào khác chỉ với 3 bước:

- name: Install Avouch
  run: python -m pip install avouch
- name: Run Avouch
  run: avouch --all-files --json

Trong CI, bạn nên dùng --all-files vì bản checkout mới thường không có thay đổi so với HEAD. Mã thoát 0 (sạch), 1 (có vi phạm), 2 (lỗi hệ thống) giúp CI dễ dàng phản hồi.

Cấu hình linh hoạt

Mọi thứ đều nằm trong file avouch.toml:

# avouch.toml — ví dụ cấu hình
ignore_paths = ["tests", "migrations"]

[limits]
max_parameters = 8        # cho phép tối đa 8 tham số thay vì 5
max_file_lines = 2500     # chấp nhận file lớn hơn

[rules]
nested_function = false   # tắt quy tắc SCR015

Bạn có thể tùy chỉnh ngưỡng cho từng quy tắc, tắt/bật từng quy tắc, và bỏ qua các đường dẫn cụ thể mà không cần cấu hình phức tạp.

Đánh giá tổng quan

Ưu điểm nổi bật:

• Miễn phí và mã nguồn mở (MIT License)
• Chạy nhanh, nhẹ, không phụ thuộc bên ngoài
• Tập trung vào diff, giảm nhiễu hiệu quả
• API JSON ổn định cho CI/CD
• 74 bài test, phủ toàn diện

Hạn chế:

• Chỉ hỗ trợ Python (không phải đa ngôn ngữ như một số dịch vụ AI)
• Không phát hiện lỗi logic hay bảo mật nâng cao
• Cần Git cho chế độ mặc định

Kết luận

Avouch là một lựa chọn thú vị cho các nhà phát triển Python đang tìm kiếm công cụ review mã nhẹ, nhanh và miễn phí. Nó không thay thế hoàn toàn các dịch vụ AI review phức tạp, nhưng giải quyết tốt nhu cầu cơ bản: bắt lỗi cấu trúc trước khi push. Với thiết kế gọn gàng, chạy cục bộ và tích hợp CI dễ dàng, đây là một dự án đáng theo dõi trong cộng đồng mã nguồn mở.

Dự án có sẵn trên GitHub tại github.com/mukundzha/avouch.