jskelet 0.1.1

package/src/server/dev/report.js

@@ -0,0 +1,351 @@
+/**
+ * "Detaylı İncele" raporunun veri katmanı.
+ *
+ * Overlay baloncuğu anlık durumu gösterir; bu modül ise sitenin tamamına
+ * bakan bir görünüm üretir: gezilen her sayfanın Web Vitals ölçümleri, SSR
+ * çıktısının boyutu, island (CSR) durumu, tarayıcı ve sunucu tarafındaki API
+ * çağrıları, build çıktısındaki chunk/varlık kırılımı ve HTML önbelleği.
+ *
+ * Yalnızca development'ta yüklenir (devtools ile birlikte mount edilir),
+ * üretim çıktısına girmez.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+import { getHtmlCacheEntries, getHtmlCacheSize } from "../html-cache.js";
+import { prewarmProgress } from "../prewarm.js";
+import { getConfig } from "../../config/index.js";
+
+/** Yollar config'ten: framework paket içine taşındığında `../..` sayan her hesap bozulur. */
+const ROOT = getConfig().root;
+const PUBLIC_DIR = getConfig().dirs.public;
+const GENERATED_DIR = getConfig().dirs.generated;
+
+/* ------------------------------------------------------------- sayfa ölçümleri */
+
+/**
+ * @typedef {{
+ *   url: string,
+ *   title: string | null,
+ *   at: number,
+ *   visits: number,
+ *   metrics: Record<string, number | null>,
+ *   resources: { count: number, bytes: number, byType: Record<string, { count: number, bytes: number }> },
+ *   islands: { total: number, ready: number, names: string[] },
+ *   api: { url: string, ms: number, status: number, bytes: number, initiator: string }[],
+ *   html: { bytes: number | null, cache: string | null, ms: number | null },
+ * }} PageReport
+ */
+
+/** @type {Map<string, PageReport>} */
+const pages = new Map();
+
+/** Tarayıcıdan gelen ölçüm paketini saklar. En yeni paket öncekini ezer. */
+export function recordPageReport(payload) {
+  if (!payload?.url) return;
+
+  let url;
+  try {
+    url = new URL(payload.url).pathname + new URL(payload.url).search;
+  } catch {
+    url = String(payload.url);
+  }
+
+  const previous = pages.get(url);
+
+  pages.set(url, {
+    url,
+    title: payload.title ?? previous?.title ?? null,
+    at: Date.now(),
+    visits: (previous?.visits ?? 0) + 1,
+    metrics: payload.metrics ?? {},
+    resources: payload.resources ?? { count: 0, bytes: 0, byType: {} },
+    islands: payload.islands ?? { total: 0, ready: 0, names: [] },
+    api: Array.isArray(payload.api) ? payload.api.slice(0, 100) : [],
+    html: previous?.html ?? { bytes: null, cache: null, ms: null },
+  });
+}
+
+/** Ölçümler tarayıcı sekmesinde değil sunucuda durur; sıfırlama da buradan. */
+export function clearPageReports() {
+  pages.clear();
+  serverApiCalls.length = 0;
+}
+
+/* --------------------------------------------------- sunucu tarafı API çağrıları */
+
+/**
+ * @type {{ url: string, host: string, method: string, status: number, ms: number,
+ *   bytes: number, at: number, error: string | null }[]}
+ */
+const serverApiCalls = [];
+const MAX_API_CALLS = 300;
+
+/**
+ * SSR sırasında yapılan dış çağrıları ölçer. `globalThis.fetch` sarılır;
+ * yalnızca dev'de çağrıldığı için üretim yolu dokunulmaz kalır.
+ */
+export function trackServerFetch() {
+  const original = globalThis.fetch;
+  if (original.__jskeletWrapped) return;
+
+  /** @type {typeof fetch} */
+  const wrapped = async (input, init) => {
+    const url = typeof input === "string" ? input : (input?.url ?? String(input));
+    const started = Date.now();
+
+    // Kendi sunucumuza yapılan istekler (ısıtma, sağlık kontrolü) API sayılmaz.
+    const isSelf = /^https?:\/\/(127\.0\.0\.1|localhost)/i.test(url);
+
+    try {
+      const response = await original(input, init);
+      if (!isSelf) {
+        push({
+          url,
+          method: init?.method ?? "GET",
+          status: response.status,
+          ms: Date.now() - started,
+          bytes: Number(response.headers.get("content-length") ?? 0),
+          error: response.ok ? null : `HTTP ${response.status}`,
+        });
+      }
+      return response;
+    } catch (error) {
+      if (!isSelf) {
+        push({
+          url,
+          method: init?.method ?? "GET",
+          status: 0,
+          ms: Date.now() - started,
+          bytes: 0,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+      throw error;
+    }
+  };
+
+  wrapped.__jskeletWrapped = true;
+  globalThis.fetch = wrapped;
+}
+
+/** @param {{ url: string, method: string, status: number, ms: number, bytes: number, error: string | null }} call */
+function push(call) {
+  let host = "—";
+  try {
+    host = new URL(call.url).host;
+  } catch {
+    // Göreli adres: host bilinmiyor.
+  }
+
+  serverApiCalls.push({ ...call, host, at: Date.now() });
+  while (serverApiCalls.length > MAX_API_CALLS) serverApiCalls.shift();
+}
+
+/* ------------------------------------------------------------ build çıktısı */
+
+/** Boyut hesapları dosya değişmedikçe tekrarlanmaz. */
+const sizeCache = new Map();
+
+/**
+ * @param {string} file mutlak yol
+ * @returns {{ bytes: number, gzip: number, brotli: number | null } | null}
+ */
+function measure(file) {
+  let stat;
+  try {
+    stat = fs.statSync(file);
+  } catch {
+    return null;
+  }
+
+  const key = `${file}:${stat.size}:${stat.mtimeMs}`;
+  const hit = sizeCache.get(key);
+  if (hit) return hit;
+
+  let gzip = 0;
+  let brotli = null;
+
+  try {
+    const buffer = fs.readFileSync(file);
+    // Build önceden sıkıştırılmış eşlerini üretiyorsa onları kullan; yoksa
+    // gzip'i burada hesapla (rapor tek seferlik, maliyeti kabul edilebilir).
+    brotli = statSize(`${file}.br`);
+    gzip = statSize(`${file}.gz`) ?? zlib.gzipSync(buffer, { level: 6 }).length;
+  } catch {
+    return null;
+  }
+
+  const value = { bytes: stat.size, gzip, brotli };
+  sizeCache.set(key, value);
+  return value;
+}
+
+/** @param {string} file @returns {number | null} */
+function statSize(file) {
+  try {
+    return fs.statSync(file).size;
+  } catch {
+    return null;
+  }
+}
+
+/** @returns {Record<string, string>} */
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Manifest girdileri + boyutları. Yol public/ altına göre çözülür.
+ */
+function assets() {
+  const manifest = readJson(path.join(GENERATED_DIR, "manifest.json"), {});
+
+  return Object.entries(manifest).map(([name, url]) => {
+    const size = measure(path.join(PUBLIC_DIR, url.replace(/^\//, "")));
+    return {
+      name,
+      url,
+      kind: path.extname(url).slice(1) || "other",
+      bytes: size?.bytes ?? null,
+      gzip: size?.gzip ?? null,
+      brotli: size?.brotli ?? null,
+    };
+  });
+}
+
+/**
+ * esbuild metafile'ından chunk analizi: her çıktı için boyut, hangi
+ * kaynaklardan oluştuğu ve hangi chunk'ları import ettiği.
+ */
+function chunks() {
+  const metafile = readJson(path.join(GENERATED_DIR, "metafile.json"), null);
+  if (!metafile?.outputs) return { outputs: [], groups: [], available: false };
+
+  /** @type {Record<string, number>} */
+  const groups = {};
+
+  const outputs = Object.entries(metafile.outputs)
+    .filter(([file]) => file.endsWith(".js") || file.endsWith(".css"))
+    .map(([file, output]) => {
+      const size = measure(path.join(ROOT, file));
+
+      const inputs = Object.entries(output.inputs ?? {})
+        .map(([source, info]) => ({ source, bytes: info.bytesInOutput ?? 0 }))
+        .filter((input) => input.bytes > 0)
+        .sort((a, b) => b.bytes - a.bytes);
+
+      for (const input of inputs) {
+        const group = groupOf(input.source);
+        groups[group] = (groups[group] ?? 0) + input.bytes;
+      }
+
+      return {
+        file: `/${file.split(path.sep).join("/").replace(/^public\//, "")}`,
+        entry: output.entryPoint ?? null,
+        isChunk: file.includes("chunks"),
+        bytes: output.bytes,
+        gzip: size?.gzip ?? null,
+        brotli: size?.brotli ?? null,
+        imports: (output.imports ?? [])
+          .filter((item) => item.kind !== "file-loader")
+          .map((item) => ({
+            path: `/${item.path.split(path.sep).join("/").replace(/^public\//, "")}`,
+            kind: item.kind,
+          })),
+        inputs: inputs.slice(0, 40),
+        inputCount: inputs.length,
+      };
+    })
+    .sort((a, b) => b.bytes - a.bytes);
+
+  return {
+    available: true,
+    outputs,
+    groups: Object.entries(groups)
+      .map(([name, bytes]) => ({ name, bytes }))
+      .sort((a, b) => b.bytes - a.bytes),
+  };
+}
+
+/**
+ * Kaynak dosyayı okunur bir gruba indirger: paket adı ya da üst klasör.
+ * @param {string} source
+ */
+function groupOf(source) {
+  const normalized = source.split(path.sep).join("/");
+  const modules = normalized.lastIndexOf("node_modules/");
+
+  if (modules >= 0) {
+    const rest = normalized.slice(modules + "node_modules/".length).split("/");
+    return rest[0].startsWith("@") ? `${rest[0]}/${rest[1]}` : rest[0];
+  }
+
+  const parts = normalized.split("/").filter(Boolean);
+  return parts.slice(0, 2).join("/") || normalized;
+}
+
+/* ------------------------------------------------------------------- rapor */
+
+/**
+ * Rapor sayfasının tek veri kaynağı.
+ * @param {{ requests: object[], errors: object[] }} devtools
+ */
+export function buildReport(devtools) {
+  const usage = process.memoryUsage();
+
+  // SSR ölçümleri: ısıtma turu her sayfanın HTML boyutunu ve render süresini
+  // biliyor; gezilen sayfalarla eşleştirilir.
+  const warmByPath = new Map(
+    (prewarmProgress.entries ?? []).map((entry) => [entry.path, entry]),
+  );
+
+  const pageList = [...pages.values()].map((page) => {
+    const warm = warmByPath.get(page.url.split("?")[0]);
+    return {
+      ...page,
+      html: warm
+        ? { bytes: warm.bytes, cache: warm.cache, ms: warm.ms }
+        : page.html,
+    };
+  });
+
+  // Hiç gezilmemiş ama ısıtılmış sayfalar da listelenir: SSR tarafı bilinir,
+  // istemci ölçümleri boş kalır.
+  for (const entry of prewarmProgress.entries ?? []) {
+    if (pages.has(entry.path)) continue;
+    pageList.push({
+      url: entry.path,
+      title: null,
+      at: prewarmProgress.finishedAt ?? prewarmProgress.startedAt,
+      visits: 0,
+      metrics: {},
+      resources: { count: 0, bytes: 0, byType: {} },
+      islands: { total: 0, ready: 0, names: [] },
+      api: [],
+      html: { bytes: entry.bytes, cache: entry.cache, ms: entry.ms },
+    });
+  }
+
+  return {
+    generatedAt: Date.now(),
+    process: {
+      pid: process.pid,
+      node: process.version,
+      uptime: process.uptime(),
+      memory: { rss: usage.rss, heapUsed: usage.heapUsed },
+      env: process.env.NODE_ENV ?? "development",
+    },
+    pages: pageList.sort((a, b) => (b.visits - a.visits) || b.at - a.at),
+    serverApi: serverApiCalls.slice().reverse(),
+    build: { assets: assets(), ...chunks() },
+    cache: { size: getHtmlCacheSize(), entries: getHtmlCacheEntries() },
+    prewarm: { ...prewarmProgress },
+    requests: devtools.requests,
+    errors: devtools.errors,
+  };
+}

package/src/server/head-hints.js

@@ -0,0 +1,132 @@
+/**
+ * `<head>` kaynak ipuçları — `react-dom`'un preconnect/preload çağrılarının
+ * karşılığı.
+ *
+ * Layout bu bloğu `<head>`in en başına basar: preconnect ve LCP preload'ını
+ * geciktirmek doğrudan LCP'ye yazılır. Preconnect listesi her sayfada aynı
+ * olduğu için bir kez hesaplanır; sayfaya özel görsel preload'ını
+ * controller `head` alanıyla `headHints()` üzerinden ekler.
+ */
+import { getConfig } from "../config/index.js";
+import { preloadImage } from "../views/helpers/tags.js";
+import { esc, jsonScript } from "../views/helpers/html.js";
+
+/** @type {string | null} */
+let cached = null;
+
+/**
+ * `jskelet.config.mjs` → `preconnect: ["https://cdn.example.com"]`.
+ * Üçüncü taraf kaynaklar (görsel CDN'i, API origin'i, font host'u) buraya
+ * yazılır. Boş liste geçerli bir yapılandırmadır.
+ *
+ * @returns {string}
+ */
+export function preconnectHints() {
+  if (cached != null) return cached;
+
+  cached = getConfig()
+    .preconnect.map((origin) => {
+      try {
+        return `<link rel="preconnect" href="${esc(new URL(origin).origin)}">`;
+      } catch {
+        console.warn(`[head] preconnect geçersiz URL, atlandı: ${origin}`);
+        return "";
+      }
+    })
+    .join("");
+
+  return cached;
+}
+
+/**
+ * Spekülasyondan her koşulda muaf tutulan bağlantılar. `nofollow` ve
+ * `target=_blank` zaten site içi gezinme değil; `data-no-prefetch` ise
+ * uygulamanın tek bir bağlantıyı elle dışarıda bırakma yolu (oturum kapatma
+ * gibi yan etkili hedefler için).
+ */
+const EXEMPT_SELECTORS = ["[rel~=nofollow]", "[target=_blank]", "[data-no-prefetch]"];
+
+/**
+ * Speculation Rules gövdesini üretir. `getConfig()`ten ayrı tutulmasının
+ * sebebi test edilebilirlik: kural üretimi saf bir dönüşüm.
+ *
+ * @param {import('../config/index.js').NavigationConfig} navigation
+ * @returns {object | null} Hiç kural yoksa `null`.
+ */
+export function buildSpeculationRules(navigation) {
+  /** @type {Record<string, object[]>} */
+  const rules = {};
+
+  // `href_matches: "/*"` yalnızca aynı origin'deki yolları eşler; dış
+  // bağlantılar için spekülasyon hem anlamsız hem gizlilik açısından istenmez.
+  const where = {
+    and: [
+      { href_matches: "/*" },
+      ...navigation.exclude.map((pattern) => ({ not: { href_matches: pattern } })),
+      ...EXEMPT_SELECTORS.map((selector) => ({ not: { selector_matches: selector } })),
+    ],
+  };
+
+  if (navigation.prefetch) {
+    rules.prefetch = [{ where, eagerness: navigation.prefetch }];
+  }
+  if (navigation.prerender) {
+    rules.prerender = [{ where, eagerness: navigation.prerender }];
+  }
+
+  return Object.keys(rules).length ? rules : null;
+}
+
+/** @type {string | null} */
+let navigationCached = null;
+
+/**
+ * Site içi gezinme ipuçları: Speculation Rules + cross-document view
+ * transition. İkisi de her sayfada aynı olduğu için bir kez hesaplanır.
+ *
+ * Bunlar bilinçli olarak client runtime'ı değil: tarayıcı bağlantı üzerinde
+ * duraksamayı, önceliklendirmeyi ve iptali kendisi yönetiyor. Aynı davranışı
+ * JS ile yazmak hem daha fazla bayt hem daha kötü bir tahmin demek.
+ *
+ * @returns {string}
+ */
+export function navigationHints() {
+  if (navigationCached != null) return navigationCached;
+
+  const { navigation } = getConfig();
+  const rules = buildSpeculationRules(navigation);
+
+  // Geçiş kuralı hem eski hem yeni belgede bulunmalı; her sayfaya basılan
+  // satır içi bir kural bunu build çıktısına bağımlı olmadan garanti eder.
+  // Hareket azaltma tercihi burada karşılanır: sayfa geçişi tam ekran bir
+  // çapraz geçiş üretir ve bu, vestibüler rahatsızlığı olan kullanıcılar için
+  // kaçınılması gereken türden bir animasyon.
+  const transition = navigation.viewTransition
+    ? "<style>@view-transition{navigation:auto}" +
+      "@media (prefers-reduced-motion:reduce){@view-transition{navigation:none}}</style>"
+    : "";
+
+  navigationCached =
+    (rules ? `<script type="speculationrules">${jsonScript(rules)}</script>` : "") +
+    transition;
+
+  return navigationCached;
+}
+
+/**
+ * İlk ekrandaki görselin preload'ı. Preconnect'leri layout zaten her sayfaya
+ * bastığı için burada tekrarlanmaz.
+ *
+ * @param {{ href?: string | null, imageSrcSet?: string,
+ *   imageSizes?: string }} [lcpImage]
+ * @returns {string}
+ */
+export function headHints(lcpImage) {
+  if (!lcpImage?.href) return "";
+
+  return preloadImage({
+    href: lcpImage.href,
+    imagesrcset: lcpImage.imageSrcSet,
+    imagesizes: lcpImage.imageSizes,
+  });
+}

package/src/server/html-cache.js

@@ -0,0 +1,166 @@
+/**
+ * ISR ikamesi: route + query anahtarlı, TTL'li LRU HTML cache.
+ *
+ * TTL dolduğunda girdi hemen atılmaz: `stale` pencerede eski HTML anında
+ * döner ve tazeleme arkada çalışır. Böylece ilk ısıtmadan sonra hiçbir istek
+ * render'ı beklemez; buna karşılık HTML'deki veri en fazla `revalidate + bir
+ * tazeleme turu` kadar geride olabilir. Fiyat gibi canlı alanlar istemcide
+ * WebSocket'ten güncellendiği için bu gecikme ekranda görünmez.
+ */
+
+/**
+ * @typedef {{ html: string, status: number, expiresAt: number,
+ *   staleUntil: number, encoded: Map<string, Buffer> }} HtmlEntry
+ */
+
+const MAX_ENTRIES = 500;
+
+/**
+ * TTL dolduktan sonra eski HTML'in kaç TTL boyunca daha servis edilebileceği.
+ * Tazeleme genelde ilk stale istekte tamamlandığı için bu pencere yalnızca
+ * yavaş upstream'lerde devreye girer.
+ */
+const STALE_FACTOR = 1;
+
+/** @type {Map<string, HtmlEntry>} */
+const store = new Map();
+
+/** @type {Map<string, Promise<{ html: string, status: number }>>} */
+const inflight = new Map();
+
+/**
+ * @param {string} key
+ * @returns {{ html: string, status: number, encoded: Map<string, Buffer>,
+ *   stale: boolean } | null}
+ */
+function read(key) {
+  const entry = store.get(key);
+  if (!entry) return null;
+
+  const now = Date.now();
+  if (now >= entry.staleUntil) {
+    store.delete(key);
+    return null;
+  }
+
+  // LRU: erişilen girdiyi sona taşı.
+  store.delete(key);
+  store.set(key, entry);
+
+  return {
+    html: entry.html,
+    status: entry.status,
+    encoded: entry.encoded,
+    stale: now >= entry.expiresAt,
+  };
+}
+
+/**
+ * @param {string} key
+ * @param {{ html: string, status: number }} value
+ * @param {number} ttlSeconds
+ */
+function write(key, value, ttlSeconds) {
+  const now = Date.now();
+
+  store.set(key, {
+    html: value.html,
+    status: value.status,
+    // Sıkıştırılmış gövdeler HTML ile aynı ömrü paylaşır: aynı sayfa her
+    // istekte yeniden brotli'lenmesin.
+    encoded: new Map(),
+    expiresAt: now + ttlSeconds * 1000,
+    staleUntil: now + ttlSeconds * 1000 * (1 + STALE_FACTOR),
+  });
+
+  while (store.size > MAX_ENTRIES) {
+    const oldest = store.keys().next().value;
+    if (oldest === undefined) break;
+    store.delete(oldest);
+  }
+}
+
+/**
+ * @param {string} key
+ * @param {number} ttlSeconds
+ * @param {() => Promise<{ html: string, status: number, degraded?: boolean }>} producer
+ * @returns {Promise<{ html: string, status: number, degraded?: boolean }>}
+ */
+function refresh(key, ttlSeconds, producer) {
+  const pending = inflight.get(key);
+  if (pending) return pending;
+
+  const task = producer()
+    .then((value) => {
+      // `degraded`: upstream düştüğü için eksik veriyle üretilmiş HTML.
+      // Saklanırsa eksik içerik tüm TTL boyunca servis edilir.
+      if (value.status === 200 && !value.degraded) {
+        write(key, value, ttlSeconds);
+      }
+      return value;
+    })
+    .finally(() => {
+      inflight.delete(key);
+    });
+
+  inflight.set(key, task);
+  return task;
+}
+
+/**
+ * @param {string} key
+ * @param {number} ttlSeconds 0 → cache yok
+ * @param {() => Promise<{ html: string, status: number }>} producer
+ * @returns {Promise<{ html: string, status: number, cached: boolean,
+ *   stale?: boolean, encoded?: Map<string, Buffer> }>}
+ */
+export async function withHtmlCache(key, ttlSeconds, producer) {
+  if (!ttlSeconds) {
+    const fresh = await producer();
+    return { ...fresh, cached: false };
+  }
+
+  const hit = read(key);
+
+  if (hit) {
+    // Süresi geçmiş girdi anında döner; tazeleme arkada yürür ve hatası
+    // isteği etkilemez (eski HTML stale penceresi boyunca geçerli kalır).
+    if (hit.stale) {
+      void refresh(key, ttlSeconds, producer).catch((error) => {
+        console.error(`[html-cache] arka plan tazelemesi başarısız: ${key}`, error);
+      });
+    }
+    return { ...hit, cached: true };
+  }
+
+  const value = await refresh(key, ttlSeconds, producer);
+  return { ...value, encoded: store.get(key)?.encoded, cached: false };
+}
+
+export function clearHtmlCache() {
+  store.clear();
+}
+
+export function getHtmlCacheSize() {
+  return store.size;
+}
+
+/**
+ * Dev raporu için önbellek dökümü: hangi sayfa ne kadar HTML tutuyor, ne
+ * zaman bayatlıyor. HTML gövdesi dönmez, yalnızca boyutu.
+ *
+ * @returns {{ key: string, bytes: number, status: number, stale: boolean,
+ *   expiresIn: number, encodings: string[] }[]}
+ */
+export function getHtmlCacheEntries() {
+  const now = Date.now();
+
+  return [...store.entries()].map(([key, entry]) => ({
+    key,
+    bytes: Buffer.byteLength(entry.html),
+    status: entry.status,
+    stale: now >= entry.expiresAt,
+    expiresIn: Math.round((entry.expiresAt - now) / 1000),
+    encodings: [...entry.encoded.keys()],
+  }));
+}