Avouch: Trình Linter AST Nhận Biết Git Chỉ Kiểm Tra Python Bạn Đã Thay Đổi

Hầu hết các linter Python đều quét toàn bộ kho lưu trữ: chúng gắn cờ mọi vấn đề trong codebase của bạn, bao gồm cả mã kế thừa bạn thừa hưởng. Avouch có cách tiếp cận khác. Nó hỏi Git tệp nào commit tiếp theo của bạn sẽ chạm tới, chỉ phân tích những tệp đó bằng mô-đun ast chuẩn, và báo cáo các vấn đề cấu trúc theo giới hạn bạn cấu hình trong avouch.toml.

Không daemon, không mạng, không cần duy trì danh sách đường dẫn. Chạy nó vài giây trước git push, sửa những gì nó gắn cờ, rồi push.

Tại sao nó tồn tại

Ý tưởng cốt lõi của Avouch là tập hợp cần kiểm tra là diff, không phải kho lưu trữ. Nó tính toán tập hợp kiểm tra từ Git tại thời điểm chạy (git diff HEAD --name-only cộng với các tệp chưa theo dõi), vì vậy mọi phát hiện đều quy cho công việc bạn sắp push, không bao giờ là mã kế thừa bạn thừa hưởng.

Các chỉ số là chính xác. Số lượng tham số, độ sâu lồng nhau và phạm vi dòng đến từ AST, không phải regex. Nếu một chỉ số không thể tính chính xác, Avouch không tuyên bố nó.

Lỗi là dữ liệu. Một tệp không đọc được hoặc sai cú pháp trở thành mục ERROR trong báo cáo. Một tệp hỏng không bao giờ hủy việc kiểm tra các tệp khác.

Avouch kiểm tra; nó không chặn. Mã thoát báo hiệu kết quả — 0 sạch, 1 tìm thấy vi phạm, 2 lỗi Avouch — nhưng việc thực thi thuộc về một giao diện chọn tham gia, không phải trong công cụ bạn chạy trước mỗi lần push.

Thời gian chạy là thư viện chuẩn. Ba lệnh gọi tiến trình con git và ast/tomllib. Không có daemon để giữ sống; thời gian chạy bị giới hạn bởi kích thước diff của bạn, không phải kho lưu trữ của bạn.

Cài đặt và bắt đầu nhanh

Yêu cầu Python 3.10+ (các quy tắc sử dụng ast.Match; cấu hình sử dụng tomllib) và Git trên PATH. Cài đặt bằng pip install avouch.

Giao diện là một lệnh với một tập nhỏ các cờ tùy chọn:

cd your-repo
# ... thực hiện thay đổi ...
avouch            # báo cáo con người
avouch --json     # một tài liệu JSON trên stdout
avouch --docs     # tài liệu tích hợp; không thực hiện kiểm tra
avouch --version  # in phiên bản và thoát
avouch --verbose  # chi tiết kiểm tra từng bước trên stderr
avouch --quiet    # phân tích, không in báo cáo; chỉ mã thoát
avouch --changed  # chế độ xem nhỏ gọn các tệp đã thêm/xóa so với HEAD
avouch --staged   # chỉ kiểm tra các tệp đã sẵn sàng cho commit tiếp theo
avouch --all-files  # kiểm tra mọi tệp Python đủ điều kiện, không chỉ diff
avouch --not-git  # kiểm tra mọi tệp .py đủ điều kiện trên đĩa; không cần kho Git
avouch --help     # mọi cờ

Tập hợp kiểm tra được xác định bởi Git, vì vậy không có gì để cấu hình tại thời điểm gọi. Avouch kiểm tra các tệp được theo dõi đã sửa đổi so với HEAD và các tệp .py chưa theo dõi. Các đường dẫn đã xóa và tệp không phải .py được bỏ qua. Các tệp đã commit, không thay đổi không bao giờ xuất hiện trong đầu ra. Các tệp trông như được tạo (generated.py, *_generated.py, codegen.py, autogen.py, …) cũng được bỏ qua.

Đầu ra và tích hợp CI

Để tự động hóa và CI, --json in bản kiểm tra dưới dạng một tài liệu JSON duy nhất trên stdout, không trộn lẫn văn bản con người. Mỗi vi phạm mang id quy tắc, mức độ nghiêm trọng, thông điệp, tệp, tên thành phần, loại (func, class, hoặc file) và dòng. Tài liệu là một hợp đồng ổn định, có phiên bản: version là phiên bản schema, tool xác định bộ phát, và cùng một đầu vào luôn tạo ra cùng một JSON — không có màu sắc, dấu thời gian hoặc chẩn đoán rò rỉ.

Mã thoát hoạt động chính xác như trong chế độ bình thường, vì vậy avouch --json có thể chặn CI: phân tích stdout để tìm phát hiện và phản ứng với trạng thái thoát (0 sạch, 1 vi phạm, 2 lỗi Avouch).

Màu sắc là mã ANSI chỉ phát ra khi stdout là TTY. Đầu ra qua pipe là trơn, vì vậy avouch | tee review.log và chụp CI hoạt động sạch. Lỗi thời gian chạy được ghi vào stderr, vì vậy stdout sạch để pipe và chụp --json.

Cấu hình và quy tắc

Avouch được cấu hình qua avouch.toml, nơi bạn đặt giới hạn như số lượng tham số tối đa, độ sâu lồng nhau và độ dài dòng. Các quy tắc được xác định bằng ID như SCR002 (bare except) và SCR014 (quá nhiều tham số). Công cụ được thiết kế để mở rộng — bạn có thể thêm quy tắc của riêng mình.

Avouch là một cách tiếp cận mới mẻ cho linting Python: nó tôn trọng thời gian của bạn bằng cách chỉ kiểm tra những gì bạn thực sự thay đổi, và tôn trọng codebase của bạn bằng cách không nhấn chìm bạn trong các vấn đề có sẵn. Nếu bạn là nhà phát triển Python muốn phản hồi nhanh, tập trung vào diff trước khi push, Avouch đáng để xem.