jskelet 0.3.5 → 0.4.1

package/src/compile/scan-exports.js

@@ -0,0 +1,51 @@
+/**
+ * Kaynak metinden named export adlarını çıkarır — modülü çalıştırmadan.
+ * Compile-time bilinen bileşen listesi için; `default` yok sayılır.
+ */
+
+/**
+ * Yorumları kaba şekilde siler; string içindeki sahte eşleşmeler nadirdir.
+ * @param {string} source
+ * @returns {string}
+ */
+function stripComments(source) {
+  return source.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
+}
+
+/**
+ * `export { a, b as C, default as X }` listesinden dışa verilen adları toplar.
+ * @param {string} clause
+ * @param {Set<string>} out
+ */
+function addExportList(clause, out) {
+  for (const part of clause.split(",")) {
+    const trimmed = part.trim();
+    if (!trimmed) continue;
+    const bits = trimmed.split(/\s+as\s+/i);
+    const exported = (bits[1] ?? bits[0]).trim();
+    if (!exported || exported === "default") continue;
+    out.add(exported);
+  }
+}
+
+/**
+ * @param {string} source
+ * @returns {string[]}
+ */
+export function scanNamedExports(source) {
+  const text = stripComments(source);
+  /** @type {Set<string>} */
+  const names = new Set();
+
+  for (const match of text.matchAll(
+    /\bexport\s+(?:async\s+)?(?:function\*?|class|const|let|var)\s+([A-Za-z_$][\w$]*)/g,
+  )) {
+    names.add(match[1]);
+  }
+
+  for (const match of text.matchAll(/\bexport\s*\{([^}]+)\}/g)) {
+    addExportList(match[1], names);
+  }
+
+  return [...names];
+}

package/src/config/defaults.js

@@ -14,8 +14,12 @@ export const IMMUTABLE_CACHE = "public, max-age=31536000, immutable";
  * tek tek ezilebilir.
  */
 export const DEFAULT_DIRS = {
-  /** EJS layout + sayfalar + bileşenler. */
+  /** Layout + sayfalar + bileşenler (klasik kök). */
   views: "views",
+  /** Feature-first dikey dilimler (`features/<name>/{server,views,client}`). */
+  features: "features",
+  /** Özellikler arası paylaşılan server/views/client. */
+  shared: "shared",
   /** Statik dosyalar; build çıktısı da buraya yazılır. */
   public: "public",
   /** Island runtime ve entry'ler. */
@@ -24,7 +28,7 @@ export const DEFAULT_DIRS = {
   routes: "routes",
   /** Tailwind/PostCSS giriş dosyası. */
   styles: "styles/globals.css",
-  /** Build ara çıktıları (manifest, metafile, images). */
+  /** Build ara çıktıları (manifest, metafile, images, templates). */
   generated: ".jskelet",
 };
 

package/src/config/index.js

@@ -801,6 +801,10 @@ function resolveDirs(root, overrides) {
  * Uygulamanın layout'u yoksa framework'ün minimal layout'u kullanılır. Bu
  * sayede yeni bir proje tek bir route ile çalışır hâle gelir.
  *
+ * Öncelik: config `layout` → `layout.jsk` (derlenmiş) → `layout.ejs` →
+ * framework varsayılanı. Dönüş değeri kaynak dosya yoludur; `.jsk` için
+ * render katmanı derlenmiş modülü kullanır.
+ *
  * @param {Record<string, string>} dirs
  * @param {string} [override]
  * @returns {string}
@@ -808,6 +812,9 @@ function resolveDirs(root, overrides) {
 function resolveLayout(dirs, override) {
   if (override) return path.resolve(dirs.views, "..", override);
 
+  const jskLayout = path.join(dirs.views, "layout.jsk");
+  if (fs.existsSync(jskLayout)) return jskLayout;
+
   const appLayout = path.join(dirs.views, "layout.ejs");
   if (fs.existsSync(appLayout)) return appLayout;
 

package/src/dev-server.mjs

@@ -236,11 +236,13 @@ function run(args, label, passthrough) {
 const WATCH_DIRS = [
   config.dirs.routes,
   config.dirs.views,
+  config.dirs.features,
+  config.dirs.shared,
   path.join(ROOT, "lib"),
   ...(config.watch ?? []).map((dir) => path.resolve(ROOT, dir)),
-];
+].filter(Boolean);
 
-const WATCH_EXTENSIONS = /\.(?:js|mjs|json|ejs)$/;
+const WATCH_EXTENSIONS = /\.(?:js|mjs|json|ejs|jsk)$/;
 
 /** @type {import('node:child_process').ChildProcess | null} */
 let server = null;

package/src/generate.mjs

@@ -0,0 +1,163 @@
+/**
+ * `jskelet generate` — feature / page / island iskeleti.
+ *
+ * Var olan dosyaların üzerine yazmaz. Route kaydı hâlâ açık `register`
+ * sözleşmesine bağlıdır; filesystem URL türetme yoktur.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import * as log from "./log.mjs";
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+function toPascal(name) {
+  return name
+    .split(/[-_/]+/)
+    .filter(Boolean)
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join("");
+}
+
+/**
+ * @param {string} file
+ * @param {string} contents
+ * @returns {boolean} yazıldı mı
+ */
+function writeIfMissing(file, contents) {
+  if (fs.existsSync(file)) {
+    log.line(`skip ${path.relative(process.cwd(), file)} (exists)`);
+    return false;
+  }
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, contents, "utf8");
+  log.line(`create ${path.relative(process.cwd(), file)}`);
+  return true;
+}
+
+/**
+ * @param {string} root
+ * @param {string[]} args
+ * @returns {Promise<void>}
+ */
+export async function generate(root, args) {
+  const [kind, target] = args;
+  if (!kind || !target) {
+    throw new Error(
+      "usage: jskelet generate <feature|page|island> <name>\n" +
+        "  feature  features/<name>/{index.js,server,views,client}\n" +
+        "  page     features/<feature>/views/pages/<name>.jsk  (name: feature/page)\n" +
+        "  island   features/<feature>/client/<name>.js       (name: feature/island)",
+    );
+  }
+
+  if (kind === "feature") {
+    await generateFeature(root, target);
+    return;
+  }
+  if (kind === "page") {
+    const [feature, page] = splitTarget(target);
+    await generatePage(root, feature, page);
+    return;
+  }
+  if (kind === "island") {
+    const [feature, island] = splitTarget(target);
+    await generateIsland(root, feature, island);
+    return;
+  }
+
+  throw new Error(`unknown generate kind: ${kind}`);
+}
+
+/**
+ * @param {string} target
+ * @returns {[string, string]}
+ */
+function splitTarget(target) {
+  const parts = target.split("/").filter(Boolean);
+  if (parts.length < 2) {
+    throw new Error(`expected <feature>/<name>, got "${target}"`);
+  }
+  return [parts[0], parts.slice(1).join("/")];
+}
+
+/**
+ * @param {string} root
+ * @param {string} name
+ */
+async function generateFeature(root, name) {
+  const base = path.join(root, "features", name);
+  writeIfMissing(
+    path.join(base, "index.js"),
+    `/**
+ * Feature route registration. Explicit paths only — no filesystem URL routing.
+ * @param {import('express').Express} app
+ * @param {{ route: Function }} api
+ */
+export default function register(app, { route }) {
+  app.get(
+    "/${name}",
+    route(async () => ({
+      view: "pages/${name}",
+      metadata: { title: "${toPascal(name)}" },
+      data: {},
+    })),
+  );
+}
+`,
+  );
+  writeIfMissing(path.join(base, "server", ".gitkeep"), "");
+  writeIfMissing(
+    path.join(base, "views", "pages", `${name}.jsk`),
+    `<section class="wrapper">
+  <h1>{{ metadata.title }}</h1>
+</section>
+`,
+  );
+  writeIfMissing(path.join(base, "client", ".gitkeep"), "");
+  log.ready({ label: `Feature ${name}` });
+}
+
+/**
+ * @param {string} root
+ * @param {string} feature
+ * @param {string} page
+ */
+async function generatePage(root, feature, page) {
+  const file = path.join(root, "features", feature, "views", "pages", `${page}.jsk`);
+  writeIfMissing(
+    file,
+    `<section class="wrapper">
+  <h1>{{ metadata.title }}</h1>
+</section>
+`,
+  );
+  log.ready({ label: `Page ${feature}/${page}` });
+}
+
+/**
+ * @param {string} root
+ * @param {string} feature
+ * @param {string} island
+ */
+async function generateIsland(root, feature, island) {
+  const file = path.join(root, "features", feature, "client", `${island}.js`);
+  writeIfMissing(
+    file,
+    `/**
+ * @param {HTMLElement} element
+ * @param {Record<string, unknown>} props
+ * @returns {void | (() => void)}
+ */
+export function mount(element, props) {
+  element.textContent = String(props.label ?? "${island}");
+}
+`,
+  );
+  log.line(
+    `Register in client/entries/main.js: "${island}": () => import("../../features/${feature}/client/${island}.js")`,
+  );
+  log.ready({ label: `Island ${feature}/${island}` });
+}

package/src/init.mjs

@@ -78,17 +78,17 @@ export default function register(app, { route }) {
 }
 `,
 
-  "views/pages/home.ejs": `<section class="wrapper">
-  <h1><%= metadata.title %></h1>
-  <p><%= message %></p>
+  "views/pages/home.jsk": `<section class="wrapper">
+  <h1>{{ metadata.title }}</h1>
+  <p>{{ message }}</p>
   <div data-island="counter" data-island-props='{"start":0}'></div>
 </section>
 `,
 
-  "views/pages/not-found.ejs": `<section class="wrapper">
+  "views/pages/not-found.jsk": `<section class="wrapper">
   <h1>404</h1>
   <p>The page you are looking for was not found.</p>
-  <p><a href="/">Back to home</a></p>
+  <p><Link href="/" text="Back to home" /></p>
 </section>
 `,
 
@@ -96,7 +96,7 @@ export default function register(app, { route }) {
 
 /**
  * Every named export under \`views/components/**\` is usable directly in
- * templates: \`<%- button({ text: "Save" }) %>\`. No import needed.
+ * templates: \`<Button text="Save" />\` in \`.jsk\` or \`<%- button({ text }) %>\` in EJS.
  *
  * @param {{ text: string, href?: string, class?: string }} props
  * @returns {string}
@@ -157,6 +157,8 @@ export function mount(element, props) {
 @source "../views";
 @source "../client";
 @source "../routes";
+@source "../features";
+@source "../shared";
 
 body {
   margin: 0;

package/src/server/render.js

@@ -14,6 +14,8 @@
  */
 import path from "node:path";
 import process from "node:process";
+import fs from "node:fs";
+import { pathToFileURL } from "node:url";
 import ejs from "ejs";
 import { withHtmlCache } from "./html-cache.js";
 import { getConfig, hook } from "../config/index.js";
@@ -40,6 +42,11 @@ import * as tags from "../views/helpers/tags.js";
 import { loadComponents } from "../views/components/loader.js";
 import { renderStatusPage } from "./status-page.js";
 import { suppressForPrewarm } from "./prewarm.js";
+import {
+  ensureTemplatesCompiled,
+  getComponentDirs,
+  getViewRoots,
+} from "../compile/index.js";
 
 const isDev = process.env.NODE_ENV === "development";
 
@@ -49,7 +56,10 @@ const isDev = process.env.NODE_ENV === "development";
  * hesaplanamaz, bu yüzden ilk render'da kurulur.
  *
  * @type {{ helpers: Record<string, unknown>, options: ejs.Options,
- *   viewsDir: string, layout: string } | null}
+ *   viewsDir: string, viewRoots: string[], layout: string,
+ *   compiled: Map<string, (data: object, helpers: object) => string>,
+ *   layoutRender: ((data: object, helpers: object) => string) | null
+ * } | null}
  */
 let engine = null;
 
@@ -61,21 +71,46 @@ async function getEngine() {
 
   const config = getConfig();
   const viewsDir = config.dirs.views;
+  const viewRoots = getViewRoots(config);
+
+  await ensureTemplatesCompiled(config);
+
+  /** @type {Record<string, unknown>} */
+  const helpers = {
+    ...html,
+    ...tags,
+    ...(await loadComponents(getComponentDirs(config))),
+    asset,
+    hasAsset,
+    // Yerleşik PascalCase etiketler (.jsk bileşen sözdizimi).
+    Link: (props) => tags.link(props),
+    Image: (props) => tags.image(props),
+    Icon: (props) => tags.icon(props),
+    CsrfField: () => tags.csrfField(),
+    PreloadImage: (props) => tags.preloadImage(props),
+  };
+
+  // camelCase JS bileşenlerini PascalCase etiket adıyla da erişilebilir yap.
+  for (const [name, value] of Object.entries(helpers)) {
+    if (typeof value !== "function") continue;
+    if (/^[A-Z]/.test(name)) continue;
+    const pascal = name.charAt(0).toUpperCase() + name.slice(1);
+    if (!(pascal in helpers)) helpers[pascal] = value;
+  }
+
+  const { compiled, layoutRender } = await loadCompiledTemplates(config, helpers);
 
   engine = {
     viewsDir,
+    viewRoots,
     layout: config.layout,
-    helpers: {
-      ...html,
-      ...tags,
-      ...(await loadComponents(path.join(viewsDir, "components"))),
-      asset,
-      hasAsset,
-    },
+    helpers,
+    compiled,
+    layoutRender,
     options: {
       // `include('partials/header')` gibi çağrılar views kökünden çözülür.
       root: viewsDir,
-      views: [viewsDir],
+      views: viewRoots.length ? viewRoots : [viewsDir],
       cache: !isDev,
       rmWhitespace: true,
       async: true,
@@ -85,6 +120,66 @@ async function getEngine() {
   return engine;
 }
 
+/**
+ * Derlenmiş `.jsk` modüllerini yükler. İstek anında parse/compile yok.
+ *
+ * @param {import('../config/index.js').ResolvedConfig} config
+ * @param {Record<string, unknown>} helpers
+ * @returns {Promise<{ compiled: Map<string, Function>, layoutRender: Function | null }>}
+ */
+async function loadCompiledTemplates(config, helpers) {
+  /** @type {Map<string, (data: object, helpers: object) => string>} */
+  const compiled = new Map();
+  const templatesDir = path.join(config.dirs.generated, "templates");
+  const manifestPath = path.join(templatesDir, "manifest.json");
+
+  if (!fs.existsSync(manifestPath)) {
+    return { compiled, layoutRender: null };
+  }
+
+  /** @type {Record<string, string>} */
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const bust = isDev ? `?t=${Date.now()}` : "";
+
+  for (const [viewId, rel] of Object.entries(manifest)) {
+    const file = path.join(templatesDir, rel);
+    if (!fs.existsSync(file)) continue;
+    const mod = await import(pathToFileURL(file).href + bust);
+    if (typeof mod.render !== "function") continue;
+    compiled.set(viewId, mod.render);
+
+    // `components/*.jsk` → helpers.PascalName
+    if (viewId.startsWith("components/")) {
+      const base = viewId.slice("components/".length).split("/").pop() ?? "";
+      const pascal = base
+        .split(/[-_/]+/)
+        .filter(Boolean)
+        .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+        .join("");
+      if (pascal) {
+        helpers[pascal] = (props) => mod.render(props ?? {}, helpers);
+      }
+    }
+  }
+
+  const layoutRender = compiled.get("layout") ?? null;
+  return { compiled, layoutRender };
+}
+
+/**
+ * View id için kaynak `.ejs` dosyasını çoklu kökte ara.
+ * @param {string[]} viewRoots
+ * @param {string} view
+ * @returns {string | null}
+ */
+function findEjsView(viewRoots, view) {
+  for (const root of viewRoots) {
+    const file = path.join(root, `${view}.ejs`);
+    if (fs.existsSync(file)) return file;
+  }
+  return null;
+}
+
 /**
  * Uygulama geliştirirken bileşen dosyaları değişince kayıt yenilenmeli.
  * Dev sunucusu süreci yeniden başlattığı için normalde gerekmez; gömülü
@@ -100,13 +195,22 @@ export function resetRenderEngine() {
  * Layout kullanmadan tek bir şablon render eder. Fragment/partial uçları
  * ve e-posta şablonları bunu kullanır.
  *
+ * Öncelik: derlenmiş `.jsk` → `.ejs`. İstek anında şablon derlenmez.
+ *
  * @param {string} view `views/` altındaki yol, uzantısız (örn. "pages/home")
  * @param {object} [data]
  * @returns {Promise<string>}
  */
 export async function renderView(view, data = {}) {
-  const { viewsDir, helpers, options } = await getEngine();
-  const file = path.join(viewsDir, `${view}.ejs`);
+  const { helpers, options, compiled, viewRoots, viewsDir } = await getEngine();
+  const renderFn = compiled.get(view);
+  if (renderFn) {
+    return renderFn({ ...data }, helpers);
+  }
+
+  const file =
+    findEjsView(viewRoots.length ? viewRoots : [viewsDir], view) ??
+    path.join(viewsDir, `${view}.ejs`);
   return ejs.renderFile(file, { ...helpers, ...data }, options);
 }
 
@@ -118,7 +222,7 @@ export async function renderView(view, data = {}) {
  * @returns {Promise<string>}
  */
 export async function renderPage(page) {
-  const { helpers, options, layout } = await getEngine();
+  const { helpers, options, layout, layoutRender } = await getEngine();
   const config = getConfig();
 
   const metadata = {
@@ -134,34 +238,43 @@ export async function renderPage(page) {
     hook("layoutContext", {}, { pathname: page.pathname ?? "", metadata }),
   ]);
 
-  return ejs.renderFile(
-    layout,
-    {
-      ...helpers,
-      ...context,
-      metadata,
-      // Boş varsayılan bilinçli: "/" yazmak her sayfayı ana sayfa sanıp
-      // logoyu <h1> olarak bastıran türde hatalara yol açıyor.
-      pathname: page.pathname ?? "",
-      lang: context.lang ?? config.brand.lang ?? "en",
-      headMeta: renderHeadMeta(metadata),
-      structuredData: context.structuredData ?? [],
-      // Preconnect her sayfada aynı; LCP preload'ını sayfa kendisi ekler.
-      // Gezinme ipuçları preconnect'ten sonra: spekülasyon bir sonraki sayfayı
-      // ilgilendiriyor, bu sayfanın LCP'sinin önüne geçmemeli.
-      extraHead:
-        preconnectHints() +
-        navigationHints() +
-        (page.head ?? "") +
-        (context.extraHead ?? ""),
-      bodyClass: page.bodyClass ?? context.bodyClass ?? "",
-      entries: page.entries ?? [],
-      devtools: isDev,
-      devBasePath: config.brand.devBasePath,
-      body,
-    },
-    options,
-  );
+  const locals = {
+    ...helpers,
+    ...context,
+    metadata,
+    // Boş varsayılan bilinçli: "/" yazmak her sayfayı ana sayfa sanıp
+    // logoyu <h1> olarak bastıran türde hatalara yol açıyor.
+    pathname: page.pathname ?? "",
+    lang: context.lang ?? config.brand.lang ?? "en",
+    headMeta: renderHeadMeta(metadata),
+    structuredData: context.structuredData ?? [],
+    // Preconnect her sayfada aynı; LCP preload'ını sayfa kendisi ekler.
+    // Gezinme ipuçları preconnect'ten sonra: spekülasyon bir sonraki sayfayı
+    // ilgilendiriyor, bu sayfanın LCP'sinin önüne geçmemeli.
+    extraHead:
+      preconnectHints() +
+      navigationHints() +
+      (page.head ?? "") +
+      (context.extraHead ?? ""),
+    bodyClass: page.bodyClass ?? context.bodyClass ?? "",
+    entries: page.entries ?? [],
+    devtools: isDev,
+    devBasePath: config.brand.devBasePath,
+    body,
+  };
+
+  if (layoutRender) {
+    return layoutRender(locals, helpers);
+  }
+
+  if (layout.endsWith(".jsk")) {
+    // Kaynak var ama derlenmemiş — ensureTemplates sonrası olmamalı.
+    throw new Error(
+      `Layout ${path.relative(config.root, layout)} is not compiled — run jskelet build`,
+    );
+  }
+
+  return ejs.renderFile(layout, locals, options);
 }
 
 /**

package/src/server/router.js

@@ -9,8 +9,8 @@
  *
  * Sıra iki şekilde belirlenir:
  *   1. `jskelet.config.mjs` → `routes: ["./routes/api.js", …]` (açık liste)
- *   2. Liste yoksa `routes/` dizini alfabetik taranır. Bu durumda dosya adına
- *      sayısal önek verin: `10-pages.js`, `50-blog.js`, `99-catch-all.js`.
+ *   2. Liste yoksa `routes/` alfabetik taranır, ardından her feature'ın
+ *      `index.js` dosyası alfabetik eklenir. Catch-all'lar için sayısal önek.
  *
  * Modül sözleşmesi: default export ya da `register` adlı named export,
  * `(app, api) => void | Promise<void>` imzasıyla. `api` içinde `route`,
@@ -61,6 +61,29 @@ function discover(dir, out = []) {
   return out;
 }
 
+/**
+ * `features/<name>/index.js` (veya `.mjs`) — feature-first kayıt noktası.
+ * @param {string} featuresDir
+ * @returns {string[]}
+ */
+function discoverFeatures(featuresDir) {
+  if (!featuresDir || !fs.existsSync(featuresDir)) return [];
+
+  return fs
+    .readdirSync(featuresDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort((a, b) => a.localeCompare(b))
+    .flatMap((name) => {
+      const dir = path.join(featuresDir, name);
+      for (const file of ["index.js", "index.mjs"]) {
+        const full = path.join(dir, file);
+        if (fs.existsSync(full)) return [full];
+      }
+      return [];
+    });
+}
+
 /**
  * Route dosyalarına geçilen framework yüzeyi.
  */
@@ -84,7 +107,7 @@ export async function registerRoutes(app) {
 
   const files = config.routes
     ? config.routes.map((entry) => path.resolve(config.root, entry))
-    : discover(config.dirs.routes);
+    : [...discover(config.dirs.routes), ...discoverFeatures(config.dirs.features)];
 
   if (!files.length) {
     console.warn(