tcknvkn/spec

TCKN ve VKN doğrulamasının kanonik sözleşmesi. Bu repo, 19 dildeki tcknvkn-* kütüphanelerinin ortak referans noktasıdır.

Dosya	İçerik
VALIDATION-SPEC.md	Normatif kurallar — algoritmalar, hata kodları, normalizasyon
golden-dataset.json	Sözleşmenin çalıştırılabilir hâli: girdi→beklenen çıktı vakaları
build-golden-dataset.js	Dataset üreteci; ürettiğini kendi referans implementasyonuyla doğrular

Neden ayrı bir repo?

Aynı algoritmanın 19 ayrı implementasyonu var. Her repo kendi testini kendi koduna göre yazarsa, hepsi kendi hatasıyla yeşil kalır — Go ile Python aynı numaraya farklı cevap verse kimse fark etmez.

Ortak bir dataset bunu tersine çevirir: soru artık "bu implementasyon doğru mu?" değil, "ortak sözleşmeye uyuyor mu?".

Sürümleme

Sürümler spec-vX.Y.Z etiketiyle işaretlenir ve etiketler GPG ile imzalıdır.

Güncel sürüm	spec-v1.0.0
golden-dataset.json SHA-256	e472cca15d825160877053da1e6e7078e8c1c18ef32fa25f5abb100bef217df9

Kırıcı değişiklik = mevcut bir vakanın beklenen sonucunun değişmesi ya da yeni bir hata kodu eklenmesi → major artışı. Ek vaka = minor artışı.

Dil repoları bunu nasıl kullanır

Her tcknvkn-* reposu golden-dataset.json'un bir kopyasını tests/ altında taşır ve beklenen SHA-256'yı kendi CI'ında sabitler:

- name: golden dataset butunlugu
  run: |
    echo "${{ env.GOLDEN_SHA256 }}  tests/golden-dataset.json" | sha256sum -c -

Kopya ayrışırsa build kırılır. Kopyalanan bir dosya zamanla sessizce farklılaşır — biri düzeltilir, on sekizi eski kalır. Bu kapı, farkı merge anında yakalar.

Gate ayrı bir iş olarak durur; dile özgü test-and-build adımlarına dokunulmamıştır.

Dataset güncelleme akışı

1. Burada değiştir. Vakayı build-golden-dataset.js içindeki tabloya ekle, node build-golden-dataset.js çalıştır. Üreteç kapsamı ve hata sırasını kendisi denetler.
2. Sürümü yükselt. README.md ve VALIDATION-SPEC.md içindeki SHA-256'yı ve sürüm numarasını güncelle. CI ikisinin de dosyayla eşleştiğini doğrular, yani unutulursa build kırılır.
3. Etiketle: git tag -s spec-vX.Y.Z → push.
4. Tüketicilere dağıt:

   node tools/sync-to-libraries.js /yol/libraries

   Her repoda kopyayı, GOLDEN_SHA256 sabitini ve sürüm yorumunu birlikte günceller. İdempotenttir; güncel repoya dokunmaz.
5. Her repoda commit + push. Dosya ve sabit aynı commit'te gitmeli — ayrı giderlerse aradaki build'ler kırılır.

Ayrışma denetimi (değişiklik yapmadan):

node tools/sync-to-libraries.js /yol/libraries --check   # ayrışan varsa exit 1

Dataset'i düzenleme

golden-dataset.json elle düzenlenmez. Vakalar build-golden-dataset.js içindeki tabloda tanımlanır, dosya oradan üretilir:

node build-golden-dataset.js          # üret
node build-golden-dataset.js --check  # güncel mi? (CI bunu çalıştırır)

Üretici, her vakanın beklenen sonucunu spec'e göre yazılmış bağımsız bir referans implementasyonla hesaplar ve hata kodlarının sırasını, kapsamı (her kod için ≥2 örnek, ≥5 geçerli değer) ve girdi tekrarını denetler.

Çıktı bayt-kararlıdır: zaman damgası, rastgelelik ya da değişken anahtar sırası içermez. SHA-256 kapısının çalışabilmesi bunu gerektirir.

Lisans

MIT — bkz. LICENSE.