jskelet 0.1.1

package/src/build/tasks/icons.mjs

@@ -0,0 +1,224 @@
+/**
+ * Phosphor SVG sprite üretimi.
+ *
+ * `@phosphor-icons/core` içindeki tek tek SVG'lerden, **yalnızca kaynakta
+ * kullanılan** ikonlar için `<symbol>` seti üretir. Tüm seti göndermek 1500+
+ * ikon, yani birkaç megabayt; kullanım taraması sprite'ı tipik olarak 10-30
+ * sembolde tutuyor.
+ *
+ * Sembol id'si: `<kebab-name>-<weight>` (örn. `arrow-right-bold`).
+ *
+ * Tarama statik metin üzerinden yapıldığı için adı çalışma anında hesaplanan
+ * bir `icon()` çağrısı sprite'a girmez. Bu yüzden ad taşıyan yapılandırma
+ * alanları (`icon: "XLogo"`) da ayrıca aranır ve `views/helpers/tags.js`
+ * dev'de eksik sembol için uyarır.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { pruneAssets, writeAsset } from "../paths.mjs";
+import * as log from "../../log.mjs";
+
+const SCAN_EXTENSIONS = new Set([".ejs", ".js", ".mjs"]);
+
+/** `icon({ … })` çağrısının tamamı; `name:` ifadesi ayrıca çözümlenir. */
+const ICON_CALL = /icon\(\s*\{([^}]*)\}/g;
+const ICON_NAME_EXPR = /name:\s*([^,}]+)/;
+const ICON_WEIGHT = /weight:\s*["']([^"']+)["']/;
+/** `data-icon="flag:fill"` ve JS nesnesindeki `"data-icon": "flag:fill"`. */
+const ICON_ATTR = /data-icon"?\s*[:=]\s*["']([a-z0-9-]+)(?::([a-z]+))?["']/g;
+
+/**
+ * İkon adı `icon()` çağrısına değişkenle geldiğinde (ör. `name: item.icon`)
+ * ad statik olarak görünmez. Bu tür adlar yapılandırma listelerinde
+ * `icon: "XLogo"` / `iconName: "XLogo"` biçiminde durur; sprite'a girmezlerse
+ * `<use>` boş kalır ve ikon görünmez.
+ */
+const ICON_NAME_PROP = /\b(?:icon|iconName)\s*[:=]\s*["']([A-Z][A-Za-z0-9]*)["']/g;
+
+/** Adın içinden çıkarılabilecek sabitler: `"X"`, `cond ? "A" : "B"`. */
+const QUOTED_NAME = /["']([A-Z][A-Za-z0-9]*)["']/g;
+
+const WEIGHTS = new Set(["thin", "light", "regular", "bold", "fill", "duotone"]);
+
+/**
+ * `ArrowRightIcon` → `arrow-right`
+ * @param {string} name
+ * @returns {string}
+ */
+function toKebab(name) {
+  return String(name)
+    .replace(/Icon$/, "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2")
+    .toLowerCase();
+}
+
+/**
+ * Paket, framework'ün değil **uygulamanın** node_modules'ünden çözülür:
+ * ikon seti uygulamanın devDependency'si.
+ *
+ * @param {string} root
+ * @returns {string | null}
+ */
+function resolveIconAssets(root) {
+  const require = createRequire(path.join(root, "package.json"));
+
+  // Paketin `exports` haritası `./package.json` alt yolunu açmıyor, bu yüzden
+  // bilinen bir asset dosyası üzerinden çözülür.
+  try {
+    const probe = require.resolve(
+      "@phosphor-icons/core/assets/regular/house.svg",
+    );
+    return path.dirname(path.dirname(probe));
+  } catch {
+    // exports kapalıysa klasörü doğrudan ara.
+  }
+
+  const direct = path.join(
+    root,
+    "node_modules",
+    "@phosphor-icons",
+    "core",
+    "assets",
+  );
+
+  return fs.existsSync(direct) ? direct : null;
+}
+
+/**
+ * @param {string} dir
+ * @param {string[]} out
+ * @returns {string[]}
+ */
+function collectFiles(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectFiles(full, out);
+    } else if (SCAN_EXTENSIONS.has(path.extname(entry.name))) {
+      out.push(full);
+    }
+  }
+
+  return out;
+}
+
+/**
+ * @param {string[]} scanDirs
+ * @returns {Set<string>} `name:weight` çiftleri
+ */
+function scanUsedIcons(scanDirs) {
+  /** @type {Set<string>} */
+  const used = new Set();
+
+  // Adı değişkenle gelen çağrıların ağırlıkları: dolaylı bulunan adlar
+  // yalnızca bu ağırlıklarda üretilir, sprite gereksiz büyümez.
+  /** @type {Set<string>} */
+  const dynamicWeights = new Set();
+
+  /** @type {Set<string>} */
+  const indirectNames = new Set();
+
+  for (const dir of scanDirs) {
+    for (const file of collectFiles(dir)) {
+      const source = fs.readFileSync(file, "utf8");
+
+      for (const match of source.matchAll(ICON_CALL)) {
+        const raw = match[1].match(ICON_WEIGHT)?.[1] ?? "regular";
+        const weight = WEIGHTS.has(raw) ? raw : "regular";
+        const expression = match[1].match(ICON_NAME_EXPR)?.[1] ?? "";
+        const names = [...expression.matchAll(QUOTED_NAME)].map((m) => m[1]);
+
+        if (!names.length) {
+          dynamicWeights.add(weight);
+          continue;
+        }
+
+        for (const name of names) used.add(`${toKebab(name)}:${weight}`);
+      }
+
+      for (const match of source.matchAll(ICON_NAME_PROP)) {
+        indirectNames.add(toKebab(match[1]));
+      }
+
+      for (const match of source.matchAll(ICON_ATTR)) {
+        const weight = match[2] ?? "regular";
+        used.add(`${match[1]}:${WEIGHTS.has(weight) ? weight : "regular"}`);
+      }
+    }
+  }
+
+  if (!dynamicWeights.size) dynamicWeights.add("regular");
+
+  for (const name of indirectNames) {
+    for (const weight of dynamicWeights) used.add(`${name}:${weight}`);
+  }
+
+  return used;
+}
+
+/**
+ * @param {string} coreAssets
+ * @param {string} name kebab
+ * @param {string} weight
+ * @returns {string | null}
+ */
+function readIconBody(coreAssets, name, weight) {
+  const fileName = weight === "regular" ? `${name}.svg` : `${name}-${weight}.svg`;
+  const filePath = path.join(coreAssets, weight, fileName);
+
+  if (!fs.existsSync(filePath)) return null;
+
+  const svg = fs.readFileSync(filePath, "utf8");
+  const inner = svg.replace(/^[\s\S]*?<svg[^>]*>/, "").replace(/<\/svg>\s*$/, "");
+  return inner.trim();
+}
+
+/**
+ * @param {import('../../config/index.js').ResolvedConfig} config
+ * @returns {Promise<Record<string, string>>}
+ */
+export async function buildIconSprite(config) {
+  const coreAssets = resolveIconAssets(config.root);
+  if (!coreAssets) {
+    log.detail("@phosphor-icons/core kurulu değil, atlandı");
+    return {};
+  }
+
+  const scanDirs = (
+    config.icons?.scan ?? ["views", "client", "routes", "lib"]
+  ).map((dir) => path.resolve(config.root, dir));
+
+  pruneAssets(["sprite."]);
+
+  const used = [...scanUsedIcons(scanDirs)].sort();
+  const symbols = [];
+  const missing = [];
+
+  for (const entry of used) {
+    const [name, weight] = entry.split(":");
+    const body = readIconBody(coreAssets, name, weight);
+
+    if (!body) {
+      missing.push(entry);
+      continue;
+    }
+
+    symbols.push(
+      `<symbol id="${name}-${weight}" viewBox="0 0 256 256">${body}</symbol>`,
+    );
+  }
+
+  const sprite = `<svg xmlns="http://www.w3.org/2000/svg" style="display:none">${symbols.join("")}</svg>`;
+  const url = writeAsset("sprite.svg", sprite);
+
+  log.detail(`${symbols.length} symbols`);
+  if (missing.length) {
+    log.warn(`${missing.length} icons missing → ${missing.join(", ")}`);
+  }
+
+  return { "sprite.svg": url };
+}

package/src/build/tasks/images.mjs

@@ -0,0 +1,244 @@
+/**
+ * `next/image` optimizer'ının build zamanı karşılığı.
+ *
+ * `public/` altındaki elle konmuş raster görseller (png/jpg) için birkaç
+ * genişlikte webp üretir ve `images.json` manifest'ine yazar.
+ * `views/helpers/tags.js` → `image()` bu manifest'e bakıp `srcset` + intrinsic
+ * `width`/`height` ekler; çağıran taraf hiçbir şey değiştirmez.
+ *
+ * Çıktılar hash'li olarak `public/assets/img/` altına düşer, yani `immutable`
+ * cache ve precompress kapsamına girerler. Kaynak dosyalar olduğu yerde kalır:
+ * manifest'te olmayan bir görsel her zaman orijinaliyle servis edilir.
+ *
+ * Manifest'e kodlayıcı imzası (`webp-q78-e4`) yazılır. Kalite ayarı değişince
+ * imza da değişir ve tüm görseller yeniden kodlanır; aksi hâlde eski ayarla
+ * üretilmiş çıktılar sessizce kalırdı.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { hash, paths } from "../paths.mjs";
+import * as log from "../../log.mjs";
+
+const SOURCE = /\.(?:png|jpe?g)$/i;
+
+/** Build çıktısı ve ikon setleri taranmaz. */
+const DEFAULT_SKIP = ["assets", "fonts"];
+
+/** Yaygın kırılma noktaları; kaynaktan büyük olanlar elenir. */
+const DEFAULT_WIDTHS = [400, 640, 960, 1280, 1920];
+
+/** Retina ekranlarda bile bunun üstü israf. */
+const MAX_WIDTH = 1920;
+
+/**
+ * @typedef {{ width: number, height: number, hash: string,
+ *   variants: { width: number, url: string }[] }} ImageEntry
+ */
+
+/**
+ * @param {string} dir
+ * @param {Set<string>} skip
+ * @returns {string[]}
+ */
+function collect(dir, skip) {
+  if (!fs.existsSync(dir)) return [];
+
+  /** @type {string[]} */
+  const files = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (skip.has(entry.name)) continue;
+      files.push(...collect(path.join(dir, entry.name), skip));
+    } else if (SOURCE.test(entry.name)) {
+      files.push(path.join(dir, entry.name));
+    }
+  }
+
+  return files;
+}
+
+/**
+ * `…\public\hero\a.png` → `/hero/a.png`
+ * @param {string} file
+ * @returns {string}
+ */
+function publicUrl(file) {
+  return `/${path.relative(paths.public, file).split(path.sep).join("/")}`;
+}
+
+/**
+ * Üretilecek genişlikler: kaynaktan büyük olanlar atılır, kaynağın kendi
+ * genişliği (MAX_WIDTH ile sınırlı) her zaman listeye girer.
+ *
+ * @param {number} intrinsic
+ * @param {number[]} widths
+ * @returns {number[]}
+ */
+function targetWidths(intrinsic, widths) {
+  const capped = Math.min(intrinsic, MAX_WIDTH);
+  const out = widths.filter((width) => width < capped);
+  out.push(capped);
+  return out;
+}
+
+/**
+ * @param {import('../../config/index.js').ResolvedConfig} config
+ * @param {typeof import('sharp')} sharp
+ * @returns {Promise<Record<string, string>>} Ana manifest'e katkı yok; görsel
+ *   manifest'i ayrı dosyaya yazılır.
+ */
+export async function buildImages(config, sharp) {
+  const widths = config.images?.widths ?? DEFAULT_WIDTHS;
+  const quality = config.images?.quality ?? 78;
+  const encoder = `webp-q${quality}-e4`;
+  const webpOptions = { quality, effort: 4 };
+
+  const skip = new Set([...DEFAULT_SKIP, ...(config.images?.skip ?? [])]);
+  const manifestPath = path.join(paths.generated, "images.json");
+  const outDir = path.join(paths.assets, "img");
+
+  const sources = collect(paths.public, skip);
+  if (!sources.length) {
+    log.detail("görsel yok, atlandı");
+    return {};
+  }
+
+  fs.mkdirSync(outDir, { recursive: true });
+
+  /** @type {Record<string, ImageEntry>} */
+  let cached = {};
+  try {
+    const data = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+    if (data.encoder === encoder) cached = data.images;
+  } catch {
+    // Manifest yok ya da kodlayıcı değişti: hepsi yeniden kodlanır.
+  }
+
+  /** @type {Record<string, ImageEntry>} */
+  const images = {};
+
+  let encoded = 0;
+  let sourceBytes = 0;
+  let outputBytes = 0;
+
+  /** @param {ImageEntry} entry */
+  const variantBytes = (entry) =>
+    entry.variants.reduce(
+      (sum, variant) =>
+        sum + fs.statSync(path.join(paths.public, variant.url.slice(1))).size,
+      0,
+    );
+
+  for (const file of sources) {
+    const url = publicUrl(file);
+    const source = fs.readFileSync(file);
+    const digest = hash(source);
+    const previous = cached[url];
+
+    // Kaynak değişmediyse ve çıktılar hâlâ yerindeyse yeniden kodlamak
+    // boşa CPU; büyük bir public/ dizininde build süresini dakikalara çıkarır.
+    if (
+      previous?.hash === digest &&
+      previous.variants.every((variant) =>
+        fs.existsSync(path.join(paths.public, variant.url.slice(1))),
+      )
+    ) {
+      images[url] = previous;
+      sourceBytes += source.length;
+      outputBytes += variantBytes(previous);
+      continue;
+    }
+
+    try {
+      const entry = await encode(sharp, {
+        file,
+        source,
+        digest,
+        widths,
+        webpOptions,
+        outDir,
+      });
+      if (!entry) continue;
+
+      images[url] = entry;
+      encoded += 1;
+      sourceBytes += source.length;
+      outputBytes += variantBytes(entry);
+    } catch (error) {
+      // Bozuk/okunamayan tek bir görsel build'i düşürmesin: manifest'te yer
+      // almazsa orijinal dosya servis edilmeye devam eder.
+      log.warn(`${url} optimize edilemedi (${error.message})`);
+    }
+  }
+
+  pruneOutputs(
+    outDir,
+    new Set(
+      Object.values(images).flatMap((entry) =>
+        entry.variants.map((variant) => variant.url),
+      ),
+    ),
+  );
+
+  fs.mkdirSync(paths.generated, { recursive: true });
+  fs.writeFileSync(
+    manifestPath,
+    `${JSON.stringify({ encoder, images }, null, 2)}\n`,
+  );
+
+  const total = Object.keys(images).length;
+  const saved = sourceBytes - outputBytes;
+  log.detail(
+    `${total} images${encoded ? ` (${encoded} encoded)` : " (cached)"}, ` +
+      `${log.size(Math.max(saved, 0))} saved`,
+  );
+
+  return {};
+}
+
+/**
+ * Manifest'te artık geçmeyen eski çıktıları siler.
+ *
+ * @param {string} outDir
+ * @param {Set<string>} keep public URL kümesi
+ */
+function pruneOutputs(outDir, keep) {
+  if (!fs.existsSync(outDir)) return;
+  for (const file of fs.readdirSync(outDir)) {
+    if (!keep.has(`/assets/img/${file}`)) {
+      fs.rmSync(path.join(outDir, file), { force: true });
+    }
+  }
+}
+
+/**
+ * @param {typeof import('sharp')} sharp
+ * @param {{ file: string, source: Buffer, digest: string, widths: number[],
+ *   webpOptions: object, outDir: string }} job
+ * @returns {Promise<ImageEntry | null>}
+ */
+async function encode(sharp, job) {
+  const { width, height } = await sharp(job.source, { failOn: "none" }).metadata();
+  if (!width || !height) return null;
+
+  const base = path.basename(job.file, path.extname(job.file));
+
+  /** @type {{ width: number, url: string }[]} */
+  const variants = [];
+
+  for (const target of targetWidths(width, job.widths)) {
+    const buffer = await sharp(job.source, { failOn: "none" })
+      .resize({ width: target, withoutEnlargement: true })
+      .webp(job.webpOptions)
+      .toBuffer();
+
+    // Hash kaynak + genişlikten türetilir: aynı içerik her build'de aynı
+    // dosya adını verir, `immutable` cache bayatlamaz.
+    const fileName = `${base}-${target}.${hash(`${job.digest}:${target}`)}.webp`;
+    fs.writeFileSync(path.join(job.outDir, fileName), buffer);
+    variants.push({ width: target, url: `/assets/img/${fileName}` });
+  }
+
+  return { width, height, hash: job.digest, variants };
+}

package/src/build/tasks/precompress.mjs

@@ -0,0 +1,78 @@
+/**
+ * Build çıktısı varlıkların brotli/gzip kopyalarını üretir.
+ *
+ * Yalnızca `public/assets/` kapsanır: oradaki dosyalar hash'li ve `immutable`,
+ * yani içerikleri hiç değişmiyor ve her istekte yeniden sıkıştırmak boşa CPU.
+ * Build'de bir kez kalite 11 ile sıkıştırmak hem sunucu yükünü sıfırlar hem de
+ * çalışma anında göze alınamayacak bir oran verir (istek anındaki kalite 5'e
+ * karşı). `public/` altındaki elle konmuş dosyalar küçük ve seyrek istendiği
+ * için çalışma anındaki sıkıştırmaya bırakılır.
+ *
+ * `server/middleware/static-precompressed.js` bu dosyaları servis eder.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import zlib from "node:zlib";
+import { paths } from "../paths.mjs";
+import * as log from "../../log.mjs";
+
+/** Zaten sıkışık formatları (woff2, png, jpg, webp) tekrar sıkıştırmak anlamsız. */
+const COMPRESSIBLE = /\.(?:css|js|mjs|svg|json|xml|txt|map)$/i;
+
+/** Bu boyutun altında sıkıştırma kazancı başlık maliyetini karşılamıyor. */
+const MIN_BYTES = 1024;
+
+const BROTLI_OPTIONS = {
+  params: {
+    [zlib.constants.BROTLI_PARAM_QUALITY]: 11,
+    [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
+  },
+};
+
+/**
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function collect(dir) {
+  if (!fs.existsSync(dir)) return [];
+
+  /** @type {string[]} */
+  const files = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) files.push(...collect(full));
+    else if (COMPRESSIBLE.test(entry.name)) files.push(full);
+  }
+
+  return files;
+}
+
+export async function precompressAssets() {
+  // Önceki turdan kalan kopyalar kaynak değişince bayatlamasın.
+  for (const file of collect(paths.assets)) {
+    for (const ext of [".br", ".gz"]) {
+      fs.rmSync(file + ext, { force: true });
+    }
+  }
+
+  let count = 0;
+  let saved = 0;
+
+  for (const file of collect(paths.assets)) {
+    const source = fs.readFileSync(file);
+    if (source.length < MIN_BYTES) continue;
+
+    const br = zlib.brotliCompressSync(source, BROTLI_OPTIONS);
+    const gz = zlib.gzipSync(source, { level: 9 });
+
+    fs.writeFileSync(`${file}.br`, br);
+    fs.writeFileSync(`${file}.gz`, gz);
+
+    count += 1;
+    saved += source.length - br.length;
+  }
+
+  log.detail(`${count} files, ${log.size(saved)}`);
+}