AI Destekli Yazılım Geliştirmede Lockfile Driftini Yönetmek

AI destekli yazılım geliştirme için lockfile drift tehdit modeli

AI destekli yazılım geliştirme akışında asıl risk, modelin package.json dosyasına eklediği paketten çok çözücünün lockfile'a yazdığı transitif grafiktir. SemVer aralığı olan ^1.2.0, ilk kurulumda 1.2.x ailesinden farklı bir sürümü çözebilir; aynı PR birkaç gün sonra yeniden üretildiğinde test edilen grafikten farklı bir grafiğe ulaşılır. Önce her PR'da manifest ve lockfile farkını ayrı ölçün: git diff --stat origin/main...HEAD -- package.json pnpm-lock.yaml. Manifest değişmeden lockfile değişmişse bunu otomatik reddetmek yerine, bot veya geliştirici tarafından yazılmış gerekçe etiketi zorunlu tutmak daha doğrudur; çünkü çözümleyici sürümü, platforma özel optional dependency veya lockfile yeniden biçimlendirmesi bu farkı üretebilir.

pnpm kullanan bir depoda çözücüyü, Node sürümünü ve lifecycle script politikasını birlikte sabitleyin. packageManager alanı sadece ekip standardı değildir: Corepack'in hangi pnpm binary'sini indireceğini belirler ve farklı geliştirici makinelerinin lockfile şemasını dönüştürmesini önler. İlk ölçüm olarak son 30 PR'da yalnız lockfile değiştiren PR sayısını ve CI'da frozen-lockfile hatası oranını kaydedin. Politika sonrası aynı iki metriği karşılaştırın; hedef, bağımlılık güncellemesini azaltmak değil, açıklamasız çözümleme değişikliklerini görünür kılmaktır.

{
  "packageManager": "pnpm@9.15.4",
  "engines": {
    "node": ">=20 <=22"
  },
  "pnpm": {
    "onlyBuiltDependencies": ["esbuild", "sharp"]
  }
}

# Yerelde ve CI'da aynı çözümleme kuralı
corepack enable
pnpm install --frozen-lockfile
pnpm why sharp

İncelik şudur: optionalDependencies ve native modüller Linux CI, macOS geliştirme makinesi ve farklı CPU mimarilerinde farklı alt paketler seçebilir. Bu nedenle lockfile'ı elle sadeleştirmek yerine pnpm why <paket> ile pakete ulaşan yolu bulun ve yalnızca hedef çalışma platformunda kullanılan imajda test edin. Bir yapay zeka eğitimi veya llm eğitimi laboratuvarında modele sadece 'paketi güncelle' demek yerine, değişiklikten sonra pnpm why, lisans denetimi ve lockfile diff özeti üretmesini istemek, generative ai çıktısını doğrulanabilir kanıta bağlar.

Vibe coding egitiminde bağımlılık değişikliğini daraltan PR sözleşmesi

Vibe coding eğitimi ve vibe coding kursu içeriklerinde yaygın hata, ajanın tek bir hata için hem framework hem lint eklentileri hem de lockfile formatını güncellemesine izin vermektir. Bunu bir PR sözleşmesiyle sınırlayın: ajan en fazla bir doğrudan bağımlılık ekleyebilsin, package manager değişmesin, çalışma zamanı major sürümü değişmesin ve her yeni paket için onu kullanan kaynak dosya belirtilebilsin. Bu sınırlar model kalitesini varsaymaz; inceleme yüzeyini deterministik olarak küçültür.

Aşağıdaki GitHub Actions adımı manifest değişmeden lockfile değişimini durdurur. BASE_REF için hedef dalı sabit yazmak yerine pull request taban SHA'sını kullanmak önemlidir; aksi halde uzun yaşayan branch'lerde ana dala sonradan gelen bağımlılık güncellemeleri yanlış pozitif üretir. Kuralın önceki ve sonraki etkisini, reddedilen PR sayısı ile güvenlik incelemesine gerçekten gönderilen PR sayısını aylık olarak karşılaştırın.

name: dependency-contract
on:
  pull_request:

jobs:
  lockfile-contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          persist-credentials: false
      - name: Reject unexplained lockfile-only changes
        env:
          BASE: ${{ github.event.pull_request.base.sha }}
        run: |
          manifest=$(git diff --name-only "$BASE" HEAD -- package.json pnpm-workspace.yaml)
          lockfile=$(git diff --name-only "$BASE" HEAD -- pnpm-lock.yaml)
          if [ -n "$lockfile" ] && [ -z "$manifest" ]; then
            echo "pnpm-lock.yaml changed without a manifest change"
            exit 1
          fi
      - name: Reproduce dependency graph
        run: |
          corepack enable
          pnpm install --frozen-lockfile
          pnpm audit --prod

Bu iş, ci cd pipeline içinde test işinden önce koşmalıdır. Nedeni basittir: test job'ı bağımlılık kurulumunda grafiği değiştirebiliyorsa test sonucu zaten incelenen commit'in sonucu değildir. Ayrıca pnpm audit tek başına yeterli kabul edilmemeli; registry danışmanlığı ile eşleşme yapar, kaynak kodda gerçekten çağrılan riskli API'leri göstermez. Yüksek etkili bir güncellemede pnpm list --depth Infinity çıktısını PR artifact'i olarak saklayın ve kritik paketin transitif mi doğrudan mı geldiğini inceleyin. Bu pratik, devops eğitimi müfredatında test yeşilken bağımlılık grafiğinin neden ayrı bir teslimat nesnesi olduğunu somutlaştırır.

Docker eğitimi: lockfile'dan immutable container imajına geçiş

Docker eğitimi kapsamında sık görülen hata, kaynak kodunu kopyaladıktan sonra pnpm install çalıştırmak ve tag ile belirtilen taban imajı kullanmaktır. Bu düzenlemede kaynak dosyasındaki her değişiklik dependency katmanını geçersiz kılar; daha kritik olarak node:20 gibi bir tag farklı zamanda farklı digest'e işaret edebilir. Aşağıdaki Dockerfile, CI'nin digest ile verdiği taban imajı kullanır, önce lockfile üzerinden paket deposunu doldurur ve kurulumda ağ erişimini keser.

# CI bu değeri registry'den çözülmüş bir digest olarak verir.
ARG NODE_IMAGE
FROM ${NODE_IMAGE} AS deps
WORKDIR /app
RUN corepack enable
COPY package.json pnpm-lock.yaml ./
RUN --mount=type=cache,id=pnpm-store,target=/pnpm/store     pnpm fetch --frozen-lockfile
RUN pnpm install --offline --frozen-lockfile --prod

FROM ${NODE_IMAGE} AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY dist ./dist
USER node
CMD ["node", "dist/server.js"]

BuildKit cache'i yalnız hız için değil, gözlemlenebilirlik için de ayırın: cache anahtarını lockfile hash'i ile ilişkilendirin ve cache hit oranını CI loglarından ölçün. Örneğin sha256sum pnpm-lock.yaml çıktısını job summary'ye yazın; aynı hash ile beklenmedik ağ indirmesi varsa offline kurulum kuralı delinmiştir. Native paketler için bir edge case vardır: geliştirme ortamında üretilmiş node_modules klasörünü runtime imajına kopyalamayın. ABI, libc türü veya CPU mimarisi uyuşmazlığı MODULE_NOT_FOUND değil, çalışma anında dinamik bağlayıcı hatası verebilir. Bağımlılık katmanını hedef Linux imajında üretin.

Trivy ile imaj ve çalışma alanını ayrı tarayın: trivy fs --scanners vuln . lockfile tabanlı riskleri, trivy image --scanners vuln $IMAGE_DIGEST ise base image katmanlarını kapsar. Bu ayrım, uygulama bağımlılığında değişiklik olmadığı halde taban imajındaki bir CVE nedeniyle yayın kararının değiştiği durumları ayırır. Docker build bağlamına .env, yerel token dosyaları ve node_modules girmesin diye en azından .dockerignore içinde bunları dışlayın; aksi halde build context bir registry katmanına taşınabilir.

Cloud native mimari, Kubernetes ve Terraform ile çalışma zamanı kanıtı

Cloud native mimari içinde container orchestration katmanı, lockfile'ın doğruluğunu tek başına garanti etmez; cluster'a hangi imaj digest'inin gittiğini kanıtlamak gerekir. Önce yerelde minikube ile digest tabanlı dağıtımı doğrulayın: minikube start --driver=docker, ardından kubectl set image deployment/api api=$IMAGE_DIGEST ve kubectl rollout status deployment/api --timeout=120s. Tag kullanıldığında registry aynı tag'i başka bir digest'e taşıyabilir; digest kullanıldığında Kubernetes'in çektiği içerik adresi PR'da taranan imajla aynıdır.

infrastructure as code tarafında image referansını değişkenleştirin, ancak serbest bir tag kabul etmeyin. Terraform doğrulamasını plan aşamasında çalıştırmak, uygulama sırasında ortaya çıkacak yanlış image referansını erkenden yakalar.

variable "image_digest" {
  type = string
  validation {
    condition     = can(regex("@sha256:[0-9a-f]{64}$", var.image_digest))
    error_message = "image_digest bir OCI sha256 digest'i olmalidir."
  }
}

resource "kubernetes_deployment_v1" "api" {
  metadata { name = "api" }
  spec {
    replicas = 2
    selector { match_labels = { app = "api" } }
    template {
      metadata { labels = { app = "api" } }
      spec {
        container {
          name  = "api"
          image = var.image_digest
        }
      }
    }
  }
}

# CI adimi
terraform fmt -check
terraform validate
terraform plan -var="image_digest=$IMAGE_DIGEST"

Bir teknoloji eğitimi programında bu akışı dört teslimatla değerlendirmek pratiktir: lockfile diff, dependency graph artifact'i, taranmış OCI digest'i ve Terraform planı. Yazılım eğitimi içinde bu laboratuvarı uygulayan ekipler, aws eğitimi veya google cloud eğitimi ortamında provider değişse bile aynı digest ve plan denetimini koruyabilir. Kubernetes eğitimi için ölçülebilir kabul kriteri de nettir: kubectl get pods -o jsonpath='{.items[*].status.containerStatuses[*].imageID}' çıktısındaki digest, CI'nin yayınladığı digest ile byte düzeyinde eşleşmelidir. Yapay zeka kursu katılımcıları için bu, modelin ürettiği kodun değil, üretim ortamına ulaşan bağımlılık grafiğinin denetlendiği sınırdır.

Sık Sorulan Sorular

AI destekli yazılım geliştirme projelerinde lockfile neden package.json ile birlikte incelenmeli?

package.json istenen sürüm aralığını, lockfile ise çözümlenmiş transitif grafiği taşır. PR'da `pnpm install --frozen-lockfile` çalıştırın ve `git diff base...HEAD -- package.json pnpm-lock.yaml` ile iki dosyayı ayrı raporlayın. Manifest olmadan lockfile değişimi için gerekçe etiketi zorunlu kılın.

Vibe coding kursu sırasında AI'nin eklediği npm paketi nasıl kontrol edilir?

Ajana doğrudan bağımlılık sayısı, package manager ve Node major sürümü için değişmez kurallar verin. PR sonunda `pnpm why paket-adi`, `pnpm audit --prod` ve `pnpm list --depth Infinity` çıktısını artifact olarak üretin. Paket kullanılmıyorsa kaynak import'u bulunamayan doğrudan bağımlılığı reddedin.

Docker eğitimi için lockfile tabanlı tekrar üretilebilir build nasıl kurulur?

Dockerfile'da önce package.json ile lockfile'ı kopyalayın, `pnpm fetch --frozen-lockfile` sonrasında `pnpm install --offline --frozen-lockfile --prod` çalıştırın. CI'da taban imajını tag yerine OCI digest olarak `--build-arg NODE_IMAGE=$NODE_IMAGE_DIGEST` ile verin ve `trivy image` ile oluşan imajı tarayın.

Kubernetes eğitimi ve minikube ile imaj digest kontrolü nasıl test edilir?

Minikube cluster'ında deployment imajını `kubectl set image deployment/api api=$IMAGE_DIGEST` ile değiştirin. `kubectl rollout status deployment/api --timeout=120s` başarılı olduktan sonra `kubectl get pods -o jsonpath='{.items[*].status.containerStatuses[*].imageID}'` çıktısını CI'daki digest ile karşılaştırın. Tag ile dağıtım bu eşitliği güvenilir biçimde vermez.