Chương 1: Repository Cloning & File Discovery

Chương 1: Repository Cloning & File Discovery#

Thành viên phụ trách: Võ Ngọc Tiến

1. Bối cảnh và mục tiêu#

Nhiệm vụ đầu tiên chuẩn bị tập mã nguồn đầu vào cho Parser Service. Repository được lựa chọn là transformers của Hugging Face, một dự án Python có quy mô đủ lớn để kiểm tra khả năng xử lý của pipeline.

Các mục tiêu chính gồm:

Sao chép trạng thái mã nguồn hiện tại bằng cơ chế shallow clone.
Tìm toàn bộ file Python hợp lệ trong repository.
Loại bỏ cache, môi trường ảo và sản phẩm build không cần phân tích.
Chuẩn hóa đường dẫn để kết quả không phụ thuộc hệ điều hành.
Lưu danh sách file và số liệu tổng hợp để Task 2 sử dụng.

Thuộc tính	Giá trị
Tổ chức	Hugging Face
Repository	`transformers`
Clone URL	`https://github.com/huggingface/transformers.git`
Ngôn ngữ phân tích	Python
Thư mục lưu cục bộ	`transformers/`

2. Sao chép repository bằng shallow clone#

Repository transformers có lịch sử phát triển lớn, trong khi bài lab chỉ phân tích snapshot mã nguồn hiện tại. Vì vậy, nhóm sử dụng --depth 1 để chỉ tải commit gần nhất:

git clone --depth 1 https://github.com/huggingface/transformers.git transformers

Cách làm này giảm dung lượng tải xuống và thời gian chuẩn bị dữ liệu so với clone toàn bộ lịch sử. Có thể kiểm tra repository đã được clone ở chế độ shallow và ghi nhận commit đang phân tích bằng hai lệnh:

git -C transformers rev-parse --is-shallow-repository
git -C transformers log -1 --oneline

Việc lưu commit ID cùng kết quả thực nghiệm là cần thiết vì số lượng file của transformers có thể thay đổi giữa các phiên bản.

3. Thiết kế chức năng File Discovery#

Chức năng discovery được cài đặt trong parser/file_discovery.py. Hàm discover_python_files() duyệt đệ quy thư mục nguồn bằng mẫu *.py, loại các đường dẫn không hợp lệ, rồi thu thập ba thuộc tính cho mỗi file:

path: đường dẫn tương đối đã chuẩn hóa về POSIX (/);
size_bytes: kích thước file theo byte;
line_count: số dòng của file.

3.1. Quy trình xử lý#

transformers/
    ↓
Duyệt đệ quy các file *.py
    ↓
Loại cache, môi trường ảo và sản phẩm build
    ↓
Chuẩn hóa đường dẫn tương đối về POSIX
    ↓
Thu thập kích thước và số dòng
    ↓
Ghi output/discovered_python_files.json

Đường dẫn tương đối được tạo bằng normalize_path() trong parser/id_utils.py. Việc chuyển đường dẫn Windows \ và Linux / về cùng định dạng POSIX giúp dữ liệu đầu ra và các định danh ở Task 2 nhất quán giữa các nền tảng.

3.2. Các thư mục bị loại trừ#

Danh sách loại trừ được quản lý tập trung bởi EXCLUDED_DIR_NAMES trong parser/config.py:

Nhóm	Thư mục
Quản lý phiên bản	`.git`, `.hg`
CI/CD	`.github`, `.circleci`
Cache	`.mypy_cache`, `.pytest_cache`, `.ruff_cache`, `__pycache__`
Sản phẩm build	`build`, `dist`, `node_modules`
Môi trường ảo	`venv`, `.venv`, `env`

tests/ và docs/ không nằm trong danh sách loại trừ hiện tại. Nếu muốn chỉ phân tích mã nguồn thư viện, cần bổ sung chúng vào cấu hình và chạy lại toàn bộ thí nghiệm; không nên chỉ thay đổi mô tả trong báo cáo.

4. Thực thi và cấu trúc đầu ra#

Chạy discovery từ thư mục gốc dự án:

python -m parser.main discover

Kết quả được ghi vào output/discovered_python_files.json theo cấu trúc:

{
  "generated_at": "2026-07-23T15:47:13.370162+00:00",
  "repository": "transformers",
  "root_path": "transformers",
  "total_python_files": 4611,
  "files": [
    {
      "path": "transformers/benchmark/__init__.py",
      "size_bytes": 0,
      "line_count": 0
    },
    {
      "path": "transformers/benchmark/benches/llama.py",
      "size_bytes": 14722,
      "line_count": 353
    },
    {
      "path": "transformers/benchmark/benchmark.py",
      "size_bytes": 12159,
      "line_count": 324
    }
  ]
}

Trong đó:

Trường	Ý nghĩa
`generated_at`	Thời điểm tạo báo cáo theo UTC
`repository`	Tên repository nguồn
`root_path`	Đường dẫn tương đối của thư mục nguồn
`total_python_files`	Tổng số file Python hợp lệ
`files`	Danh sách file cùng kích thước và số dòng

Tệp JSON này vừa là minh chứng cho Task 1, vừa là dữ liệu có thể kiểm tra lại trước khi Parser Service xử lý toàn bộ repository.

5. Kết quả thực nghiệm#

Lần chạy được ghi nhận trong ảnh minh chứng cho kết quả:

Chỉ số	Kết quả
Tổng số file Python	4.611
Tệp kết quả	`output/discovered_python_files.json`
Định dạng đường dẫn	Tương đối, chuẩn POSIX

Danh sách file Python đã khám phá

Hình 1.1: discovered_python_files.json ghi nhận 4.611 file Python và thông tin chi tiết của từng file được quét.

Số liệu 4.611 được sử dụng nhất quán cho lần thực nghiệm này. Nếu repository được cập nhật sang commit khác hoặc tập thư mục loại trừ thay đổi, cần chạy lại discover, cập nhật ảnh và đồng bộ số liệu của Chapter 2.

6. Khả năng tái lập và giới hạn#

Để tái lập kết quả, cần ghi nhận đồng thời:

Commit hiện tại của repository transformers;
Phiên bản Python;
Tập EXCLUDED_DIR_NAMES;
Lệnh chạy và thời điểm tạo báo cáo.

Discovery chỉ lọc theo phần mở rộng và tên thư mục. Nó chưa đánh giá file có parse thành công hay không; trách nhiệm đó thuộc Parser Service ở Chapter 2. Số dòng được đọc với UTF-8 và cơ chế thay thế ký tự lỗi, vì vậy file có encoding khác vẫn được thống kê nhưng có thể cần xử lý riêng khi phân tích cú pháp.

7. Kết luận#

Shallow clone đáp ứng đúng nhu cầu lấy snapshot mã nguồn mà không tải lịch sử không cần thiết. File Discovery tạo danh sách đầu vào có thứ tự ổn định, đường dẫn thống nhất và số liệu có thể kiểm chứng. Kết quả này là cơ sở để Task 2 xử lý từng file, tạo CPG và theo dõi thay đổi theo content hash.