04/sourcemaps

Source Map Kasası & Production Debugging

Son kullanıcılara .js.map dosyalarını asla sızdırmadan Sentry ve Datadog üzerinde tam yığın izi (stack-trace) çözümlemesini koruyun.

.unpeek-maps/ İzolasyonu Nasıl Çalışır?

Üretim klasörünüzde `.map` dosyalarını bırakmak, herhangi bir kullanıcının Chrome DevTools üzerinden tüm TypeScript kaynak ağacınızı tek tıkla görmesine yol açar. Source map üretimini tamamen kapatmak ise üretim hatalarında mühendislik ekibinizi kör bırakır.

unpeek bu ikilemi `unpeek protect` aşamasında otomatik olarak çözer:

  • Hedef derleme dizinindeki tüm `*.map` dosyalarını tarar ve ECMA-426 `.sections` indeks haritalarını otomatik düzleştirir.
  • Ön ek satır kaydırmalı çok geçişli $M_1 \circ M_2$ VLQ bileşimini (`chainSourceMaps`) hesaplar; URL kodlu Next.js parçalarını (`%28public%29`, `%5Bsayi%5D`) ve Windows yollarını çözer.
  • Korumalı JS paketine ve `.unpeek-maps/` kasasındaki `.map` dosyasına aynı deterministik SHA-256 `debugId` imzasını basar (`unpeek check` `debugid-mismatch` kuralıyla doğrular) ve `//# sourceMappingURL=...` direktiflerini temizler.

CI Hattında Kasadaki Map Dosyalarını Sentry / Datadog'a Yükleme

CI iş akışınızda `unpeek protect` tamamlandıktan sonra, gözlemlenebilirlik aracınızı (`sentry-cli` veya `datadog-ci`) `.unpeek-maps/` dizinine yönlendirerek sembolleri yükleyebilir ve ardından statik dağıtım öncesinde bu klasörü silebilirsiniz.

GitHub Actions: .unpeek-maps Klasörünü Sentry'ye Yükleme
- name: İstemci Paketlerini Derle ve Koru
  run: |
    pnpm build
    npx unpeek protect

- name: Gizli Source Map Dosyalarını Sentry'ye Yükle
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
  run: |
    npx @sentry/cli sourcemaps upload \
      --org acme-corp \
      --project web-client \
      .unpeek-maps

Docker İmaj Güvenliği & .dockerignore Uyarısı

`COPY . .` komutu kullanılan Docker derlemelerinde `.dockerignore` dosyası bulunmadığında veya `.unpeek-maps/` kuralı eksik olduğunda, gizli hata ayıklama sembolleri istem dışı olarak herkese açık Docker imaj katmanlarına sızabilir.

`unpeek protect` çalıştığında mevcut `.dockerignore` dosyasını otomatik olarak `.unpeek-maps/` ile günceller. Eğer `.dockerignore` bulunmuyorsa veya kural eksikse unpeek açık bir advisory uyarısı verir:

  • `[unpeek:advisory] .dockerignore is missing .unpeek-maps/. Private maps may leak into Docker image during 'COPY . .'.`
  • Docker konteyner imajlarını yayınlamadan önce `.unpeek-maps/` dizininin hem `.gitignore` hem de `.dockerignore` içinde yer aldığından emin olun.