jskelet 0.3.5 → 0.4.0

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(

package/src/views/components/loader.js

@@ -1,7 +1,6 @@
 /**
- * `views/components/**` altındaki tüm modülleri yükler ve named export'larını
- * tek bir nesnede birleştirir. Bu nesne EJS şablonlarına local olarak geçer,
- * böylece `<%- card({ … }) %>` gibi çağrılar import gerektirmeden çalışır.
+ * `views/components/**` (ve feature/shared köklerindeki eşleri) altındaki
+ * tüm modülleri yükler ve named export'larını tek bir nesnede birleştirir.
  *
  * Elle bakılan bir barrel dosyası yok: yeni bir bileşen eklemek için dosyayı
  * oluşturmak yeterli.
@@ -44,17 +43,15 @@ function collect(dir, out = []) {
 }
 
 /**
- * @param {string} dir `views/components` dizininin mutlak yolu. Dizin yoksa
- *   boş nesne döner: bileşen kullanmayan bir proje de çalışmalı.
- * @returns {Promise<Record<string, unknown>>}
+ * Tek bir `components/` dizinini yükler.
+ *
+ * @param {string} dir
+ * @param {Record<string, unknown>} components
+ * @param {Map<string, string>} origin
+ * @returns {Promise<void>}
  */
-export async function loadComponents(dir) {
-  if (!dir || !fs.existsSync(dir)) return {};
-
-  /** @type {Record<string, unknown>} */
-  const components = {};
-  /** @type {Map<string, string>} */
-  const origin = new Map();
+async function loadDir(dir, components, origin) {
+  if (!dir || !fs.existsSync(dir)) return;
 
   const barrel = path.join(dir, BARREL);
   const files = [
@@ -80,6 +77,22 @@ export async function loadComponents(dir) {
       origin.set(name, relative);
     }
   }
+}
+
+/**
+ * @param {string | string[]} dirs Tek dizin veya çoklu kök (feature/shared).
+ * @returns {Promise<Record<string, unknown>>}
+ */
+export async function loadComponents(dirs) {
+  /** @type {Record<string, unknown>} */
+  const components = {};
+  /** @type {Map<string, string>} */
+  const origin = new Map();
+
+  const list = Array.isArray(dirs) ? dirs : [dirs];
+  for (const dir of list) {
+    await loadDir(dir, components, origin);
+  }
 
   return components;
 }