Skip to content
Apothem
Referensi

Header Kepengarangan — Baris Lisensi SPDX per Berkas

Mendefinisikan dan menegakkan penanda pengidentifikasi lisensi SPDX per berkas menggunakan header satu baris kanonik dalam sintaks komentar yang sesuai untuk setiap tipe berkas.

Referensi normatif kanonik untuk kontributor hilir. Dokumen ini mencerminkan bagian Authorship & File-Header dari spesifikasi proyek (Spec §0.5 + §4.6); dokumen ini adalah referensi mandiri yang dikirimkan bersama repo yang dipublikasikan. Dasar pemikiran arsitekturalnya dicatat di ADR-0002.

1. Baris Header Kanonik

Setiap berkas yang berlaku dalam ekosistem HARUS diawali dengan satu baris pengidentifikasi lisensi SPDX kanonik, dalam sintaks komentar keluarga tipe berkasnya; hanya shebang atau, pada berkas Markdown, frontmatter YAML yang boleh mendahuluinya (§5). Baris itu adalah penanda lisensi berkas yang terbaca mesin; keberadaannya tidak dapat ditawar untuk berkas yang tidak dikecualikan, dan isinya diatur oleh satu sumber kebenaran, tidak diimprovisasi per berkas. Instrumen hak cipta lengkap berada satu kali di berkas LICENSE di root repositori — instrumen itu tidak diduplikasi ke setiap berkas sumber.

1.1 Isi Informasi (Invarian)

Isi kanonik tepat satu baris:

  1. SPDX-License-Identifier: MIT — penanda lisensi yang terbaca mesin sesuai spesifikasi REUSE yang dipelihara oleh FSFE; diurai tanpa ambiguitas oleh toolchain SPDX (reuse lint, scancode), perkakas kernel Linux, dan pemindai lisensi hilir. Baris ini tidak membawa bingkai visual dan tidak membawa baris hak cipta, situs web, email, atau GitHub per berkas — provenance per berkas adalah baris SPDX tunggal secara rancangan (lihat §4).

1.2 Bentuk Rujukan (Keluarga Komentar #)

Teks kanonik — ditulis di sini dalam bentuk sintaks komentar # — adalah sumber kebenaran di src/apothem/schemas/authorship-header.txt:

# SPDX-License-Identifier: MIT

Teks ini adalah satu-satunya sumber otoritatif. Validator file-header (§8) memeriksa berkas terhadap fixture byte-persis ini. Setiap penyimpangan antara baris header berkas dan fixture ini (dengan substitusi sintaks sesuai §2) dilaporkan sebagai temuan. Validator ini bersifat memblokir: dengan --strict, seperti yang dijalankan oleh CI dan hook pre-commit, sebuah temuan menggagalkan eksekusi (§8).

2. Varian per Tipe Berkas (Byte-Persis)

Isi informasi baris itu invarian; hanya sintaks komentarnya yang bervariasi per tipe berkas. Tabel varian per tipe berkas yang lengkap:

Keluarga tipe berkasSintaks komentarRendering varian
Keluarga # — .sh, .bash, .zsh, .py, .rb, .pl, .ps1, .yml, .yaml, .toml, .cff, .cfg, .gitignore, .gitattributes, .editorconfig, .shellcheckrc, .env.example, Makefile, Dockerfile, Procfile, CODEOWNERS, PKGBUILD, entrypoint shell tanpa ekstensi seperti scripts/apothemkomentar baris ## SPDX-License-Identifier: MIT
Keluarga // — .js, .jsx, .mjs, .cjs, .ts, .tsx, .go, .rs, .java, .kt, .swift, .cs, .scala, .dart, .jsonckomentar baris //// SPDX-License-Identifier: MIT
Keluarga komentar blok — .html, .htm, .md, .markdown, .xml, .vue (bagian templat), .php (bagian templat)<!-- ... --><!-- SPDX-License-Identifier: MIT -->
MDX (.mdx){/* ... */} (komentar ekspresi JSX){/* SPDX-License-Identifier: MIT */}
Keluarga blok-C — .c, .cc, .cpp, .h, .hpp, .css, .scss, .less (/* */)/* ... *//* SPDX-License-Identifier: MIT */
Keluarga ; — .ini, sebagian .lisp/.scmkomentar baris ;; SPDX-License-Identifier: MIT
Keluarga -- — .sql, .lua, .hs, .elm, .adakomentar baris ---- SPDX-License-Identifier: MIT
Lockfile / hasil generasi / JSONtidak ada / tidak berlakuDikecualikan. Lihat §3 Daftar Pengecualian.

Varian Markdown (rendering kanonik):

<!-- SPDX-License-Identifier: MIT -->

Pembungkus komentar HTML (atau {/* */} pada MDX) dirender tak terlihat, sehingga permukaan yang dirender tetap bersih sementara penanda lisensi di dalam sumber tetap terbaca mesin di semua tipe berkas.

3. Daftar Pengecualian (Dikecualikan secara Kategoris)

Kelas-kelas berikut dikecualikan dari baris header SPDX. Validator file-header melewati berkas-berkas ini tanpa memeriksanya. Kelas di bawah ini cocok dengan daftar glob di header-exceptions.txt:

  • Berkas legal dan versi — LICENSE, LICENSE.md, LICENSE.txt, NOTICE, dan VERSION. LICENSE memuat baris hak cipta otoritatif, yang keberadaannya dikonfirmasi oleh validator license-author-consistency.
  • Fixture kanonik — schemas/authorship-header.txt. Menyuntikkan header ke dalam fixture akan menghasilkan header dari header.
  • Aset *.svg — komentar XML rapuh untuk penanda komentar baris, sehingga provenans SVG dibawa oleh README aset dan keluaran raster yang dihasilkan.
  • Berkas JSON (.json) — JSON tidak memiliki sintaks komentar. Jika atribusi diperlukan untuk konfigurasi JSON, letakkan berkas <file>.NOTICE.md di sebelahnya.
  • Lockfile — setiap berkas *.lock, package-lock.json, yarn.lock, pnpm-lock.yaml, dan go.sum. Berkas-berkas ini dikelola mesin.
  • Berkas hasil generasi dan minified — setiap berkas di bawah direktori generated/, serta bundel minified (*.min.js, *.min.css).
  • Konten pihak ketiga yang di-vendor — berkas di bawah _vendor/, vendor/, third_party/, dan node_modules/. Berkas-berkas ini membawa lisensi atau pemberitahuan milik upstream. Menyuntikkan penanda kami di atas atribusi upstream adalah pelanggaran lisensi.
  • Status audit, perencanaan, dan harness — semua yang berada di bawah .audit/ dan .apothem/, yang berisi rencana, memori, data pembelajaran, dan konteks. Juga projects/ dan memory/ di root working-tree, yang dimiliki harness. Pohon-pohon ini di-gitignore atau dimiliki operator dan berada di luar cakupan pohon yang dipublikasikan. Berkas rencana dilacak provenansnya melalui frontmatter-nya (lihat plans-discipline.md §3).
  • Fixture data tes — berkas .yaml, .yml, .txt, dan .json di bawah tests/fixtures/. Berkas sumber tes di pohon tersebut tetap membawa header.
  • Masukan smoke-test injektor — berkas di bawah tests/conformity-scenarios/fixtures/F-13-injector-smoke/. Berkas-berkas ini tetap tanpa header karena tes injektor memeriksa bahwa injektor menambahkan header ke dalamnya.
  • Kemasan dan penanda kosong — .SRCINFO, yang dibaca secara ketat oleh parser kemasan, serta penanda nol-byte .keep, .gitkeep, dan py.typed.
  • Berkas biner — sufiks gambar, font, arsip, media, dan objek terkompilasi yang tercantum di fixture. Sufiks yang tidak dipetakan oleh tabel varian validator dikecualikan secara bawaan.

Daftar pengecualian itu sendiri dikodekan sebagai daftar regex/glob di src/apothem/schemas/header-exceptions.txt dan menjadi masukan bagi pemeriksaan keberlakuan validator. Perubahan memerlukan kueri terstruktur dan ADR baru.

4. Interaksi Lisensi

Baris SPDX mendeklarasikan lisensi proyek secara terbaca mesin; berkas LICENSE mendeklarasikannya secara otoritatif:

  • SPDX-License-Identifier: MIT — penanda lisensi yang terbaca mesin sesuai spesifikasi REUSE dan standar SPDX. Pemindai lisensi otomatis mengurai baris ini secara langsung; sintaks ekspresi SPDX kompatibel dengan reuse lint, scancode-toolkit, FOSSology, dan perkakas lisensi kernel Linux.
  • LICENSE di root repositori — instrumen hukum otoritatif yang memuat ketentuan MIT lengkap dan pemegang hak cipta. Berkas ini satu-satunya tempat pernyataan hak cipta; header per berkas merujuknya secara implisit melalui pengidentifikasi SPDX bersama, alih-alih mengulang pernyataan hak cipta di setiap berkas.

Bentuk satu baris. Provenance per berkas adalah baris SPDX tunggal; instrumen hak cipta berada satu kali di LICENSE root. Kotak banner multibaris berbingkai (baris hak cipta, situs web, email, dan kontak yang dibungkus dalam bingkai bergaris) ditolak oleh validator: kotak itu menduplikasi metadata kontak dan hak cipta di setiap berkas tanpa menambahkan apa pun yang belum disediakan penanda lisensi terbaca mesin kepada perkakas REUSE/SPDX/SBOM. Fixture byte-persis di src/apothem/schemas/authorship-header.txt memuat bentuk satu baris; validator dijalankan terhadap fixture ini.

Rujukan silang. Berkas LICENSE (MIT) — jika terjadi konflik, instrumen hukum yang berlaku. ADR-0006 mendokumentasikan dasar pemikiran ratifikasi penyempitan banner.

5. Posisi Penyisipan

  • Baris SPDX adalah konten pertama berkas, dengan dua pengecualian. Baris shebang (#!/usr/bin/env bash, #!/usr/bin/env python3, dsb.) selalu tetap berada di baris 1, dan baris SPDX dimulai di baris 2. Pada berkas Markdown / MDX dengan frontmatter YAML, frontmatter berada di urutan pertama (butir berikutnya).
  • Untuk berkas Markdown / MDX dengan frontmatter YAML, frontmatter tetap berada di byte 0 agar perkakas dapat mengurainya, dan komentar SPDX mengikuti --- penutup, lalu isi berkas, yang dibuka dengan H1 pada berkas yang memilikinya. scripts/inject-header.py menempatkan komentar dengan cara ini.
  • Satu baris kosong memisahkan baris SPDX dari konten berikutnya (H1, isi, dsb.).

6. Kebijakan Visibilitas Header

Untuk berkas Markdown dan MDX, baris SPDX selalu ditulis di dalam pembungkus komentarnya (<!-- ... --> atau {/* */}). Baris ini hanya terlihat di sumber dan tidak muncul pada halaman yang dirender. Injektor tidak memiliki rendering yang terlihat dan tidak memiliki penimpaan per berkas. Tidak ada alat dalam repositori yang membaca fixture src/apothem/schemas/header-visibility.yaml.

7. Injektor — scripts/inject-header.{sh,py}

CLI deterministik yang:

  • Menerima satu atau lebih jalur berkas (atau glob).
  • Menentukan keberlakuan melalui daftar pengecualian (§3).
  • Mendeteksi status header yang ada (kanonik / cacat / tidak ada), dengan menghapus setiap blok banner non-kanonik yang ditemukannya agar eksekusi ulang bersifat idempoten.
  • Merender varian SPDX yang benar per tipe berkas (§2).
  • Menyisipkan pada posisi yang benar (§5), dengan menghormati shebang dan frontmatter.
  • Menambahkan baris kosong yang hilang pada baris SPDX yang berada di lokasi penyisipan tanpa baris kosong tersebut, alih-alih menyisipkan salinan kedua di atasnya.
  • Beroperasi dalam tiga mode: fix-in-place (menulis), emit-patch (mencetak diff terpadu), check (keluar dengan kode bukan nol pada setiap penyimpangan; tidak ada job CI yang menjalankannya pada pohon yang dilacak).
  • Idempoten: menjalankannya dua kali tidak mengubah apa pun.

Injektor dipanggil oleh target make headers-fix, yang menjalankan scripts/inject-header.py --mode fix-in-place.

8. Validator — file-header

Berada di src/apothem/conformity/file_header_grep.py. Untuk setiap berkas di working tree, validator mencari keberlakuannya (sesuai §3) dan, jika berlaku, menegaskan bahwa baris SPDX kanonis ada di posisi penyisipan. Untuk sebagian besar keluarga, posisi itu adalah kepala berkas, setelah shebang opsional. Untuk berkas Markdown dan MDX, blok frontmatter YAML dilewati terlebih dahulu, sehingga baris kanonis dapat mengikuti pagar penutup, sebagaimana diwajibkan §5. Berkas MDX di-resolve ke bentuk {/* */} (§2) dan diperiksa terhadapnya. Validator dan injector menempatkan blok kanonis pada indeks yang sama.

Didukung oleh fixture byte-persis di src/apothem/schemas/authorship-header.txt. Eksekusi korpus melaporkan jumlah temuan dan sampel berkas yang ditandai untuk matcher ini. Tidak ada diff per berkas dan persentase cakupan yang dicetak. Matcher bersifat memblokir: dengan --strict, yang digunakan CI dan hook pre-commit, sebuah temuan menggagalkan eksekusi. Tanpa --strict, gerbang melaporkan temuan dan keluar dengan 0.

9. Mekanisme Penegakan Mandiri

Disiplin ini harus bertahan melewati setiap sesi mendatang dan setiap kontributor mendatang. Permukaan penegakan wajib:

  1. src/apothem/schemas/authorship-header.txt — fixture kanonik byte-persis; satu sumber kebenaran.
  2. scripts/inject-header.{sh,py} — injektor mekanis (§7).
  3. Validator file-header (§8) — melaporkan penyimpangan sebagai temuan yang memblokir, yang menggagalkan eksekusi --strict.
  4. Hook pre-commit — hook conformity-corpus-perwrite menjalankan setiap matcher per-Write, termasuk validator file-header (§8), atas pohon yang dilacak dengan --strict. Matcher file-header bersifat memblokir, sehingga temuannya memblokir commit. Hook ini hanya memeriksa. Hook ini tidak memiliki mode perbaikan dan tidak pernah menjalankan injektor (§7), yang berjalan melalui make headers-fix.
  5. Blok perilaku wajib CLAUDE.md — menginstruksikan asisten untuk menyuntikkan baris SPDX kanonik setiap kali membuat berkas yang berlaku.
  6. Berkas instruksi GitHub Copilot di .github/copilot-instructions.md — menginstruksikan Copilot untuk melakukan hal yang sama saat menghasilkan berkas.
  7. Hook PreToolUse di src/apothem/hooks/messages/pretooluse-{write,edit}-header-guard.md — mencegat pemanggilan tool Write/Edit pada jalur yang berlaku agar baris SPDX disuntikkan saat berkas dibuat, bukan baru ditemukan sebagai temuan validator di kemudian hari. Pemeriksa milik guard tersebut, src/apothem/hooks/lib/header_check.py, hanya menggunakan pustaka standar dan membaca fixture serta daftar pengecualian dari direktori schemas/ di samping hooks/, sehingga pemeriksa ini juga bekerja di bawah plugin Claude Code, tempat paket apothem tidak dapat diimpor. Pemeriksa ini menerapkan tabel varian dan aturan lokasi penyisipan milik injektor pada berkas di dalam proyek, dan hanya dalam proyek git yang membawa fixture header (src/apothem/schemas/authorship-header.txt), karena baris SPDX adalah konvensi repositori ini dan bukan bawaan untuk setiap proyek yang dibuka plugin.
  8. Kotak centang templat PR — pernyataan untuk kontributor bahwa setiap berkas baru membawa baris SPDX kanonik.
  9. Dokumen ini (site/content/docs/reference/authorship-header.mdx) — penjelasan kanonik dan normatif.

Lihat Juga

Konvensi Harness Multi-Permukaan

Referensi normatif kanonik untuk konfigurasi dan koherensi harness multi-permukaan di seluruh runtime chat, pelengkapan IDE, dan tinjauan PR.

Manifes Penyematan Dependensi

Kebijakan deklarasi dependensi yang mencakup rentang runtime Python, perkakas pengembangan, berkas kunci perkakas rilis, dan batas bawah versi yang diratifikasi untuk setiap permukaan build.

On this page

1. Baris Header Kanonik1.1 Isi Informasi (Invarian)1.2 Bentuk Rujukan (Keluarga Komentar #)2. Varian per Tipe Berkas (Byte-Persis)3. Daftar Pengecualian (Dikecualikan secara Kategoris)4. Interaksi Lisensi5. Posisi Penyisipan6. Kebijakan Visibilitas Header7. Injektor — scripts/inject-header.{sh,py}8. Validator — file-header9. Mekanisme Penegakan MandiriLihat Juga