Gerbang konformitas

Gerbang konformitas di src/apothem/conformity/gate.py menjalankan bagian mekanis dari gerbang pra-emisi lima-belas-bar (M1-M15) terhadap setiap artefak yang ditulis operator.

Perintah pada halaman ini mengasumsikan checkout Apothem, sehingga awali setiap perintah yang Anda jalankan dengan PYTHONPATH=src. Setelah pemasangan skrip, gunakan PYTHONPATH="$HOME/.apothem/src" sebagai pengganti PYTHONPATH=src.

Menjalankan gerbangCopy Anchor Link

Gerbang ini bersifat advisori secara default: gerbang melaporkan temuan dan keluar dengan 0, sehingga eksekusi lokal tidak pernah memblokir Anda. Tambahkan --strict (atau setel APOTHEM_CONFORMITY_STRICT=1) untuk keluar dengan kode bukan nol pada temuan yang memblokir — mode yang digunakan CI dan pre-commit untuk menggagalkan perubahan yang melanggar.

# Advisory: report every validator's findings across the repo, exit 0
PYTHONPATH=src python -m apothem.conformity.gate --all .

# Strict: exit non-zero (code 2) when a blocking finding is present
PYTHONPATH=src python -m apothem.conformity.gate --all --strict .

Kode keluar: 0 bersih (atau advisori), 2 pemblokiran temuan mode strict, 3 kesalahan penggunaan: flag atau nama validator yang tidak dikenal, berkas yang tidak ada, atau direktori root yang tidak ada. --help mencetak penggunaan lengkap dan keluar dengan 0. Setiap validator standalone menerima --help yang sama dan keluar dengan 3 pada flag yang tidak dikenal atau root yang hilang.

Root relatif seperti . di-resolve menjadi jalur absolut sebelum validator apa pun berjalan, sehingga --all . dan --all "$PWD" memeriksa pohon yang sama. Setiap validator melaporkan inspected — berapa banyak target yang diperiksanya — dan --all menyalin hitungan tersebut ke setiap entri hasil. Validator yang tidak memeriksa apa pun melaporkan passed: false, sehingga direktori kerja yang salah tidak dapat lolos diam-diam. Dua validator suite rencana merupakan salah satu pengecualian: suite rencana berada di pohon .apothem/plans/ yang di-gitignore, sehingga keduanya melaporkan empty_scope_expected: true pada checkout yang bersih dan tetap lolos. Validator alur kerja melakukan hal yang sama ketika proyek belum memiliki direktori .github/workflows/, dan validator subjek commit melakukannya ketika root tidak memiliki riwayat commit.

Enam validator mulai dari root repositori dan menelusuri seluruh pohon untuk mencari berkas yang mereka periksa:

agents-md-coverage-grep
agnosticism-grep
dynamism-grep
freshness-token-grep
plain-language-grep
reference-token-grep

Validator-validator ini melewati checkout git bersarang, seperti worktree, submodule, dan klon bersarang, serta melewati direktori yang menampung dependensi, lingkungan virtual, cache, atau keluaran build, seperti node_modules, venv, dan dist. Pemeriksaan rencana-nyasar di no-global-plans-grep juga berhenti pada checkout bersarang. Eksekusi salah satu validator ini melaporkan checkout yang ditunjuknya dan tidak ada yang lain. Validator yang membaca satu folder tetap, seperti naming-grep di bawah src/apothem/, membaca semua yang ada di bawah folder tersebut.

Bar gerbangCopy Anchor Link

Pemeriksaan tertargetCopy Anchor Link

# List every registered validator
PYTHONPATH=src python -m apothem.conformity.gate --list

# Run one per-write validator against one file
PYTHONPATH=src python -m apothem.conformity.gate --check multi-surface-coherence src/apothem/rules/my-rule.md

# Run one standalone validator over a root directory
PYTHONPATH=src python -m apothem.conformity.gate --check naming-grep .

# Run every per-write validator against one file
PYTHONPATH=src python -m apothem.conformity.gate src/apothem/rules/my-rule.md

Validator per-penulisan menerima berkas yang akan diperiksa, atau --stdin untuk membaca konten dari standard input; tanpa keduanya, validator menunggu masukan di standard input, jadi berikan berkasnya saat Anda menjalankannya dari terminal. Validator standalone menerima direktori root (direktori saat ini jika dihilangkan). --list menunjukkan kelompok tempat setiap validator berada.

Mode --hook (python -m apothem.conformity.gate --hook) adalah entry point yang di-dispatch oleh harness: mode ini membaca payload JSON tool-input dari stdin dan menjalankan rantai matcher per-penulisan terhadap penulisan yang tertunda. Inilah bentuk yang dipanggil oleh hook PreToolUse yang di-deploy; Anda jarang memanggilnya secara manual.

Mode hook dibatasi pada sekumpulan direktori. Mode ini menjalankan rantai matcher hanya pada penulisan yang targetnya berada di bawah salah satu direktori tersebut; penulisan di luar setiap cakupan langsung dihentikan sebagai lolos tanpa pesan. Default-nya ada dua root:

~/.claude      Claude Code
$CODEX_HOME    Codex (~/.codex when CODEX_HOME is not set)

Setel APOTHEM_CONFORMITY_SCOPE ke sebuah direktori untuk menggantikan keduanya:

# Run the per-write matcher chain against one project tree instead
export APOTHEM_CONFORMITY_SCOPE=/path/to/project

Hook yang tampak tidak melakukan apa-apa biasanya merupakan cakupan yang meleset, bukan kegagalan — periksa terlebih dahulu target penulisan terhadap cakupan di atas.

Integrasi CICopy Anchor Link

Job quality di .github/workflows/ci.yml menjalankan gerbang dalam mode strict (python -m apothem.conformity.gate --all . --strict) pada push ke main dan pada pull request ke main yang menyentuh jalur yang dipantau job tersebut. Alur kerja terpisah .github/workflows/conformity.yml menjalankan sapuan fixture (tests/conformity-scenarios/verify.py --strict).