jskelet 0.5.5 → 0.6.1

package/src/migrate/apply.mjs

@@ -0,0 +1,262 @@
+/**
+ * Codemod apply: pages / components / islands → JSkelet ağacı.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { scanProject } from "./scan.mjs";
+import { splitPage } from "./transform/page-split.mjs";
+import { transformComponent } from "./transform/jsx-to-component.mjs";
+import { transformIsland } from "./transform/island.mjs";
+import { jsxToJsk } from "./transform/jsx-to-jsk.mjs";
+import { parseSource } from "./parse.mjs";
+import { t } from "./babel.mjs";
+import { commitWrites } from "./write.mjs";
+
+/**
+ * @typedef {{
+ *   file: string,
+ *   kind: string,
+ *   status: 'ok' | 'partial' | 'skipped',
+ *   notes: string[],
+ *   outputs: string[],
+ * }} FileReport
+ */
+
+/**
+ * @param {string} sourceRoot Next projesi
+ * @param {string} outRoot JSkelet hedefi
+ * @param {{ write?: boolean, only?: Set<string>, strict?: boolean }} options
+ * @returns {Promise<{ reports: FileReport[], writes: object[] }>}
+ */
+export async function applyMigrate(sourceRoot, outRoot, options = {}) {
+  const scan = scanProject(sourceRoot);
+  /** @type {FileReport[]} */
+  const reports = [];
+  /** @type {{ path: string, contents: string }[]} */
+  const pending = [];
+
+  const only = options.only ?? null;
+  const want = (/** @type {string} */ k) => !only || only.has(k);
+
+  if (want("pages")) {
+    for (const page of scan.pages) {
+      const code = fs.readFileSync(page.abs, "utf8");
+      if (page.classification?.isClient || page.classification?.hasHooks) {
+        reports.push({
+          file: page.rel,
+          kind: "page",
+          status: "skipped",
+          notes: ["page is a client component — convert to island + server shell manually"],
+          outputs: [],
+        });
+        continue;
+      }
+      const viewId = `pages/${page.page}`;
+      const result = splitPage(code, page.rel, {
+        url: page.url,
+        feature: page.feature,
+        page: page.page,
+        viewId,
+      });
+      /** @type {string[]} */
+      const outputs = [];
+      if (result.controller) {
+        const dest = path.join(outRoot, "features", page.feature, "index.js");
+        pending.push({ path: dest, contents: result.controller });
+        outputs.push(path.relative(outRoot, dest).replace(/\\/g, "/"));
+      }
+      if (result.jsk) {
+        const dest = path.join(
+          outRoot,
+          "features",
+          page.feature,
+          "views",
+          "pages",
+          `${page.page}.jsk`,
+        );
+        pending.push({ path: dest, contents: result.jsk });
+        outputs.push(path.relative(outRoot, dest).replace(/\\/g, "/"));
+      }
+      reports.push({
+        file: page.rel,
+        kind: "page",
+        status: result.status,
+        notes: result.notes,
+        outputs,
+      });
+    }
+
+    // Root layout only (depth 0)
+    const rootLayout = scan.layouts.find((l) => l.depth === 0);
+    if (rootLayout) {
+      const code = fs.readFileSync(rootLayout.abs, "utf8");
+      const layoutResult = transformRootLayout(code, rootLayout.rel);
+      if (layoutResult.jsk) {
+        const dest = path.join(outRoot, "views", "layout.jsk");
+        pending.push({ path: dest, contents: layoutResult.jsk });
+        reports.push({
+          file: rootLayout.rel,
+          kind: "layout",
+          status: layoutResult.status,
+          notes: layoutResult.notes,
+          outputs: ["views/layout.jsk"],
+        });
+      } else {
+        reports.push({
+          file: rootLayout.rel,
+          kind: "layout",
+          status: layoutResult.status,
+          notes: layoutResult.notes,
+          outputs: [],
+        });
+      }
+    }
+  }
+
+  if (want("components")) {
+    for (const comp of scan.components) {
+      const code = fs.readFileSync(comp.abs, "utf8");
+      const result = transformComponent(code, comp.rel);
+      /** @type {string[]} */
+      const outputs = [];
+      if (result.code && result.name) {
+        const fileName = camelToKebab(result.name) + ".js";
+        const dest = path.join(outRoot, "views", "components", fileName);
+        pending.push({ path: dest, contents: result.code });
+        outputs.push(path.relative(outRoot, dest).replace(/\\/g, "/"));
+      }
+      reports.push({
+        file: comp.rel,
+        kind: "component",
+        status: result.status,
+        notes: result.notes,
+        outputs,
+      });
+    }
+  }
+
+  if (want("islands")) {
+    for (const client of scan.clients) {
+      const code = fs.readFileSync(client.abs, "utf8");
+      const result = transformIsland(code, client.rel);
+      /** @type {string[]} */
+      const outputs = [];
+      if (result.code) {
+        const dest = path.join(outRoot, "features", "migrated", "client", `${result.islandName}.js`);
+        pending.push({ path: dest, contents: result.code });
+        outputs.push(path.relative(outRoot, dest).replace(/\\/g, "/"));
+      }
+      reports.push({
+        file: client.rel,
+        kind: "island",
+        status: result.status,
+        notes: result.notes,
+        outputs,
+      });
+    }
+  }
+
+  const writes = commitWrites(
+    pending.map((p) => ({ path: p.path, contents: p.contents, action: /** @type {const} */ ("create") })),
+    { write: Boolean(options.write), cwd: outRoot },
+  );
+
+  return { reports, writes, scan };
+}
+
+/**
+ * @param {string} code
+ * @param {string} filename
+ * @returns {{ status: 'ok' | 'partial' | 'skipped', notes: string[], jsk: string | null }}
+ */
+function transformRootLayout(code, filename) {
+  /** @type {string[]} */
+  const notes = [];
+  try {
+    const ast = parseSource(code, filename);
+    const pageFn = findDefaultExportJsx(ast);
+    if (!pageFn) {
+      return {
+        status: "skipped",
+        notes: ["root layout: no default export JSX (children slot?) — copy framework layout and edit"],
+        jsk: null,
+      };
+    }
+    // Replace {children} with {{{ body }}}
+    const { source, report } = jsxToJsk(pageFn);
+    let jsk = source.replace(/\{\{\s*children\s*\}\}/g, "{{{ body }}}");
+    notes.push(...report.notes);
+    notes.push("review layout: wire <Stylesheets />, <BodyScripts />, hooks.layoutContext");
+    return {
+      status: report.status === "ok" ? "partial" : report.status,
+      notes,
+      jsk: `{# Migrated from ${filename} — prefer jskelet/layout as a starting point #}\n${jsk.trim()}\n`,
+    };
+  } catch (error) {
+    return {
+      status: "skipped",
+      notes: [error instanceof Error ? error.message : String(error)],
+      jsk: null,
+    };
+  }
+}
+
+/**
+ * @param {import('@babel/types').File} ast
+ * @returns {import('@babel/types').JSXElement | import('@babel/types').JSXFragment | null}
+ */
+function findDefaultExportJsx(ast) {
+  for (const node of ast.program.body) {
+    if (!t.isExportDefaultDeclaration(node)) continue;
+    const d = node.declaration;
+    let body = null;
+    if (t.isFunctionDeclaration(d)) body = d.body;
+    else if ((t.isArrowFunctionExpression(d) || t.isFunctionExpression(d)) && t.isBlockStatement(d.body)) {
+      body = d.body;
+    } else if ((t.isArrowFunctionExpression(d) || t.isFunctionExpression(d)) && (t.isJSXElement(d.body) || t.isJSXFragment(d.body))) {
+      return d.body;
+    }
+    if (!body) continue;
+    for (const stmt of body.body) {
+      if (t.isReturnStatement(stmt) && stmt.argument) {
+        let arg = stmt.argument;
+        if (t.isParenthesizedExpression(arg)) arg = arg.expression;
+        if (t.isJSXElement(arg) || t.isJSXFragment(arg)) return arg;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+function camelToKebab(name) {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .replace(/_/g, "-")
+    .toLowerCase();
+}
+
+/**
+ * @param {FileReport[]} reports
+ * @returns {string}
+ */
+export function formatApplyReport(reports) {
+  const lines = ["Migrate apply report", ""];
+  let ok = 0;
+  let partial = 0;
+  let skipped = 0;
+  for (const r of reports) {
+    if (r.status === "ok") ok++;
+    else if (r.status === "partial") partial++;
+    else skipped++;
+    const outs = r.outputs.length ? ` → ${r.outputs.join(", ")}` : "";
+    lines.push(`[${r.status}] ${r.kind} ${r.file}${outs}`);
+    for (const n of r.notes) lines.push(`    - ${n}`);
+  }
+  lines.push("");
+  lines.push(`Summary: ${ok} ok, ${partial} partial, ${skipped} skipped`);
+  return lines.join("\n");
+}

package/src/migrate/babel.mjs

@@ -0,0 +1,79 @@
+/**
+ * Migrate (JSX/TSX → .jsk) için Babel — opsiyonel peer.
+ *
+ * Normal `build` / `start` / `dev` bunları indirmez. İlk parse anında paket
+ * yoksa kurulum komutunu gösteren net bir hata verir.
+ */
+import { createRequire } from "node:module";
+import path from "node:path";
+import process from "node:process";
+import { FRAMEWORK_ROOT } from "../config/index.js";
+
+const MISSING =
+  "`jskelet migrate` requires optional peer dependencies `@babel/parser` and `@babel/types`.\n" +
+  "Install them in the project you are migrating:\n" +
+  "  npm i -D @babel/parser @babel/types";
+
+/**
+ * @typedef {{
+ *   parse: typeof import('@babel/parser').parse,
+ *   types: typeof import('@babel/types'),
+ * }} BabelApi
+ */
+
+/** @type {BabelApi | null | undefined} */
+let cached;
+
+/**
+ * @param {string} [root] Hedef proje kökü (varsayılan: cwd).
+ * @returns {BabelApi}
+ */
+export function getBabel(root = process.cwd()) {
+  if (cached) return cached;
+  if (cached === null) throw new Error(MISSING);
+
+  for (const base of [root, FRAMEWORK_ROOT]) {
+    try {
+      const require = createRequire(path.join(base, "package.json"));
+      const parser = require("@babel/parser");
+      const types = require("@babel/types");
+      cached = {
+        parse: parser.parse.bind(parser),
+        types,
+      };
+      return cached;
+    } catch {
+      // Sonraki köke bak.
+    }
+  }
+
+  cached = null;
+  throw new Error(MISSING);
+}
+
+/**
+ * Migrate girişinde erken ve anlaşılır hata için.
+ *
+ * @param {string} [root]
+ */
+export function ensureBabel(root) {
+  getBabel(root);
+}
+
+/**
+ * `@babel/types` — ilk erişimde peer'ları yükler.
+ * Metodlar doğru `this` ile bağlanır (`t.isIdentifier(node)`).
+ *
+ * @type {typeof import('@babel/types')}
+ */
+export const t = /** @type {typeof import('@babel/types')} */ (
+  new Proxy(/** @type {object} */ ({}), {
+    get(_target, prop) {
+      // Promise thenable tuzağına düşmesin.
+      if (prop === "then") return undefined;
+      const types = getBabel().types;
+      const value = Reflect.get(types, prop, types);
+      return typeof value === "function" ? value.bind(types) : value;
+    },
+  })
+);

package/src/migrate/classify.mjs

@@ -0,0 +1,155 @@
+/**
+ * Bir kaynak dosyasını page / layout / client / server-component olarak sınıflandırır.
+ */
+import path from "node:path";
+import { t } from "./babel.mjs";
+import { parseSource } from "./parse.mjs";
+
+/**
+ * @typedef {'page' | 'layout' | 'client' | 'server-component' | 'unknown'} FileKind
+ * @typedef {{
+ *   kind: FileKind,
+ *   isClient: boolean,
+ *   hasHooks: boolean,
+ *   hasServerAction: boolean,
+ *   hasSuspense: boolean,
+ *   revalidate: number | null,
+ *   hasGenerateMetadata: boolean,
+ *   hasGenerateStaticParams: boolean,
+ *   reasons: string[],
+ * }} Classification
+ */
+
+/**
+ * @param {string} code
+ * @param {string} filename
+ * @returns {Classification}
+ */
+export function classifySource(code, filename) {
+  const base = path.basename(filename);
+  /** @type {Classification} */
+  const out = {
+    kind: "unknown",
+    isClient: false,
+    hasHooks: false,
+    hasServerAction: false,
+    hasSuspense: false,
+    revalidate: null,
+    hasGenerateMetadata: false,
+    hasGenerateStaticParams: false,
+    reasons: [],
+  };
+
+  if (/^["']use client["'];?/.test(code.trim()) || /\n["']use client["'];?/.test(code)) {
+    out.isClient = true;
+  }
+  if (code.includes('"use server"') || code.includes("'use server'")) {
+    out.hasServerAction = true;
+    out.reasons.push("contains \"use server\"");
+  }
+
+  let ast;
+  try {
+    ast = parseSource(code, filename);
+  } catch (error) {
+    out.reasons.push(
+      `parse error: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    if (out.isClient) out.kind = "client";
+    else if (/^page\./.test(base)) out.kind = "page";
+    else if (/^layout\./.test(base)) out.kind = "layout";
+    return out;
+  }
+
+  for (const node of ast.program.directives ?? []) {
+    if (node.value?.value === "use client") out.isClient = true;
+    if (node.value?.value === "use server") {
+      out.hasServerAction = true;
+      out.reasons.push("directive \"use server\"");
+    }
+  }
+
+  for (const node of ast.program.body) {
+    if (t.isImportDeclaration(node)) {
+      const src = node.source.value;
+      if (src === "react" || src === "react/jsx-runtime") {
+        for (const spec of node.specifiers) {
+          const name =
+            (t.isImportSpecifier(spec) && t.isIdentifier(spec.imported)
+              ? spec.imported.name
+              : null) ||
+            (t.isImportDefaultSpecifier(spec) ? "default" : null);
+          if (name === "Suspense") out.hasSuspense = true;
+          if (
+            name &&
+            /^(use[A-Z]|useState|useEffect|useMemo|useCallback|useRef|useContext|useReducer|useLayoutEffect|useId|useTransition|useDeferredValue|useSyncExternalStore)/.test(
+              name,
+            )
+          ) {
+            out.hasHooks = true;
+          }
+        }
+      }
+    }
+
+    if (
+      t.isExportNamedDeclaration(node) &&
+      node.declaration &&
+      t.isVariableDeclaration(node.declaration)
+    ) {
+      for (const decl of node.declaration.declarations) {
+        if (t.isIdentifier(decl.id) && decl.id.name === "revalidate") {
+          if (t.isNumericLiteral(decl.init)) out.revalidate = decl.init.value;
+          else if (t.isLiteral(decl.init) && typeof decl.init.value === "number") {
+            out.revalidate = /** @type {number} */ (decl.init.value);
+          }
+        }
+      }
+    }
+
+    if (t.isExportNamedDeclaration(node)) {
+      const id = namedExportName(node);
+      if (id === "generateMetadata") out.hasGenerateMetadata = true;
+      if (id === "generateStaticParams") out.hasGenerateStaticParams = true;
+    }
+  }
+
+  // Hook çağrıları (import alias olmadan da)
+  if (/\buse(State|Effect|Memo|Callback|Ref|Context|Reducer)\s*\(/.test(code)) {
+    out.hasHooks = true;
+  }
+
+  if (out.isClient || out.hasHooks) {
+    out.kind = "client";
+  } else if (/^page\./.test(base)) {
+    out.kind = "page";
+  } else if (/^layout\./.test(base)) {
+    out.kind = "layout";
+  } else {
+    out.kind = "server-component";
+  }
+
+  return out;
+}
+
+/**
+ * @param {import('@babel/types').ExportNamedDeclaration} node
+ * @returns {string | null}
+ */
+function namedExportName(node) {
+  if (node.declaration) {
+    if (t.isFunctionDeclaration(node.declaration) && node.declaration.id) {
+      return node.declaration.id.name;
+    }
+    if (t.isVariableDeclaration(node.declaration)) {
+      const id = node.declaration.declarations[0]?.id;
+      if (t.isIdentifier(id)) return id.name;
+    }
+  }
+  for (const spec of node.specifiers) {
+    if (t.isExportSpecifier(spec) && t.isIdentifier(spec.exported)) {
+      return spec.exported.name;
+    }
+  }
+  return null;
+}

package/src/migrate/config.mjs

@@ -0,0 +1,126 @@
+/**
+ * next.config → jskelet.config.mjs taslağı.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { findNextConfig, findClientEnvKeys } from "./fs-walk.mjs";
+
+/**
+ * @param {string} root
+ * @returns {Promise<{ status: 'ok' | 'partial' | 'skipped', notes: string[], code: string | null }>}
+ */
+export async function draftConfig(root) {
+  /** @type {string[]} */
+  const notes = [];
+  const configPath = findNextConfig(root);
+  const clientEnv = findClientEnvKeys(root);
+
+  /** @type {Record<string, unknown>} */
+  let next = {};
+
+  if (!configPath) {
+    notes.push("no next.config.* — emitting minimal jskelet.config.mjs");
+  } else if (configPath.endsWith(".ts")) {
+    notes.push("next.config.ts cannot be imported — copy headers/redirects/rewrites manually");
+  } else {
+    try {
+      const mod = await import(pathToFileURL(configPath).href);
+      next = mod.default ?? mod;
+      if (typeof next === "function") {
+        next = await next({ default: {} });
+      }
+    } catch (error) {
+      notes.push(
+        `could not load next.config: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+
+  const trailingSlash = Boolean(next.trailingSlash);
+  const deviceSizes =
+    next.images && typeof next.images === "object" && Array.isArray(next.images.deviceSizes)
+      ? next.images.deviceSizes
+      : null;
+
+  if (next.experimental) {
+    notes.push("experimental.* has no JSkelet equivalent — ignored");
+  }
+  if (fs.existsSync(path.join(root, "middleware.ts")) || fs.existsSync(path.join(root, "middleware.js"))) {
+    notes.push("middleware.ts/js → port to Express middleware manually");
+  }
+
+  const headersSrc = fnSource(next.headers, "headers", notes);
+  const redirectsSrc = fnSource(next.redirects, "redirects", notes);
+  const rewritesSrc = fnSource(next.rewrites, "rewrites", notes);
+
+  const clientEnvList =
+    clientEnv.length > 0
+      ? clientEnv.map((k) => JSON.stringify(k)).join(", ")
+      : "";
+
+  const imagesBlock = deviceSizes
+    ? `\n  images: {\n    widths: ${JSON.stringify(deviceSizes)},\n  },\n`
+    : "";
+
+  const code =
+    `/**\n` +
+    ` * Drafted by \`jskelet migrate config\` from ${configPath ? path.basename(configPath) : "defaults"}.\n` +
+    ` * Review before use — complex path-to-regexp patterns are not supported.\n` +
+    ` */\n` +
+    `export default {\n` +
+    `  brand: { lang: "en" },\n` +
+    (trailingSlash ? `  trailingSlash: true,\n` : "") +
+    (clientEnvList ? `  clientEnv: [${clientEnvList}],\n` : "") +
+    imagesBlock +
+    (headersSrc ? `\n  async headers() {\n${headersSrc}\n  },\n` : "") +
+    (redirectsSrc ? `\n  async redirects() {\n${redirectsSrc}\n  },\n` : "") +
+    (rewritesSrc ? `\n  async rewrites() {\n${rewritesSrc}\n  },\n` : "") +
+    `\n  hooks: {\n` +
+    `    metadata() {\n` +
+    `      return {\n` +
+    `        titleTemplate: "%s | Site",\n` +
+    `        description: "",\n` +
+    `      };\n` +
+    `    },\n` +
+    `    layoutContext() {\n` +
+    `      return { bodyClass: "min-h-full" };\n` +
+    `    },\n` +
+    `    notFound() {\n` +
+    `      return {\n` +
+    `        view: "pages/not-found",\n` +
+    `        metadata: { title: "Page not found", robots: { index: false } },\n` +
+    `      };\n` +
+    `    },\n` +
+    `  },\n` +
+    `};\n`;
+
+  return {
+    status: notes.length ? "partial" : "ok",
+    notes,
+    code,
+  };
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} name
+ * @param {string[]} notes
+ * @returns {string | null}
+ */
+function fnSource(value, name, notes) {
+  if (typeof value !== "function") return null;
+  try {
+    const src = Function.prototype.toString.call(value);
+    // "async headers() { ... }" or "headers() { ... }" or arrow
+    const bodyMatch = src.match(/^[^{]*\{([\s\S]*)\}$/);
+    if (!bodyMatch) {
+      notes.push(`${name}() could not be inlined — copy manually`);
+      return `    // TODO[jskelet-migrate]: paste ${name}() from next.config\n    return [];`;
+    }
+    return bodyMatch[1].replace(/^\n/, "").replace(/\n$/, "");
+  } catch {
+    notes.push(`${name}() could not be serialized`);
+    return `    // TODO[jskelet-migrate]: paste ${name}() from next.config\n    return [];`;
+  }
+}