jskelet 0.5.5 → 0.6.0

package/src/migrate/fs-walk.mjs

@@ -0,0 +1,191 @@
+/**
+ * Next App Router ağacında dosya keşfi ve path → URL eşlemesi.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const PAGE_RE = /^page\.(jsx?|tsx?|mjs|cjs)$/;
+const LAYOUT_RE = /^layout\.(jsx?|tsx?|mjs|cjs)$/;
+const SOURCE_RE = /\.(jsx?|tsx?|mjs|cjs)$/;
+
+/**
+ * @param {string} root
+ * @returns {string | null}
+ */
+export function findAppDir(root) {
+  for (const candidate of ["app", "src/app"]) {
+    const abs = path.join(root, candidate);
+    if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) return abs;
+  }
+  return null;
+}
+
+/**
+ * @param {string} root
+ * @returns {string | null}
+ */
+export function findNextConfig(root) {
+  for (const name of [
+    "next.config.mjs",
+    "next.config.js",
+    "next.config.cjs",
+    "next.config.ts",
+  ]) {
+    const abs = path.join(root, name);
+    if (fs.existsSync(abs)) return abs;
+  }
+  return null;
+}
+
+/**
+ * @param {string} dir
+ * @param {(rel: string, abs: string) => void} visit
+ * @param {string} [base]
+ */
+export function walkFiles(dir, visit, base = dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkFiles(abs, visit, base);
+      continue;
+    }
+    visit(path.relative(base, abs).replace(/\\/g, "/"), abs);
+  }
+}
+
+/**
+ * App Router segment yolunu Express path'ine çevirir.
+ * `news/[slug]` → `/news/:slug`, `docs/[...slug]` → `/docs/:slug*`
+ *
+ * @param {string} relativeDir app/ altındaki dizin (posix, trailing slash yok)
+ * @returns {string}
+ */
+export function segmentToExpressPath(relativeDir) {
+  if (!relativeDir || relativeDir === ".") return "/";
+  const parts = relativeDir.split("/").filter(Boolean);
+  const out = [];
+  for (const part of parts) {
+    if (part.startsWith("(") && part.endsWith(")")) continue; // route groups
+    if (part.startsWith("@")) continue; // parallel routes
+    const catchAll = part.match(/^\[\.\.\.(.+)\]$/);
+    if (catchAll) {
+      out.push(`:${catchAll[1]}*`);
+      continue;
+    }
+    const optional = part.match(/^\[\[\.\.\.(.+)\]\]$/);
+    if (optional) {
+      out.push(`:${optional[1]}*`);
+      continue;
+    }
+    const dyn = part.match(/^\[(.+)\]$/);
+    if (dyn) {
+      out.push(`:${dyn[1]}`);
+      continue;
+    }
+    out.push(part);
+  }
+  return "/" + out.join("/");
+}
+
+/**
+ * Feature adı: ilk anlamlı segment veya `home`.
+ *
+ * @param {string} relativeDir
+ * @returns {string}
+ */
+export function featureNameFromDir(relativeDir) {
+  const parts = relativeDir
+    .split("/")
+    .filter(Boolean)
+    .filter((p) => !(p.startsWith("(") && p.endsWith(")")))
+    .filter((p) => !p.startsWith("@"))
+    .filter((p) => !p.startsWith("["));
+  if (parts.length === 0) return "home";
+  return parts[0].replace(/[^a-zA-Z0-9_-]/g, "-") || "home";
+}
+
+/**
+ * Sayfa dosya gövde adı.
+ *
+ * @param {string} relativeDir
+ * @returns {string}
+ */
+export function pageNameFromDir(relativeDir) {
+  const parts = relativeDir
+    .split("/")
+    .filter(Boolean)
+    .filter((p) => !(p.startsWith("(") && p.endsWith(")")))
+    .filter((p) => !p.startsWith("@"));
+  if (parts.length === 0) return "home";
+  const last = parts[parts.length - 1];
+  if (last.startsWith("[")) {
+    return parts.length > 1 ? parts[parts.length - 2] : "detail";
+  }
+  return last.replace(/[^a-zA-Z0-9_-]/g, "-") || "page";
+}
+
+/**
+ * @param {string} appDir
+ * @returns {{ pages: Array<{ abs: string, rel: string, dir: string, url: string, feature: string, page: string }>, layouts: Array<{ abs: string, rel: string, dir: string, depth: number }>, sources: Array<{ abs: string, rel: string }> }}
+ */
+export function inventoryApp(appDir) {
+  /** @type {Array<{ abs: string, rel: string, dir: string, url: string, feature: string, page: string }>} */
+  const pages = [];
+  /** @type {Array<{ abs: string, rel: string, dir: string, depth: number }>} */
+  const layouts = [];
+  /** @type {Array<{ abs: string, rel: string }>} */
+  const sources = [];
+
+  walkFiles(appDir, (rel, abs) => {
+    const base = path.basename(rel);
+    const dir = path.posix.dirname(rel);
+    const dirKey = dir === "." ? "" : dir;
+
+    if (PAGE_RE.test(base)) {
+      pages.push({
+        abs,
+        rel,
+        dir: dirKey,
+        url: segmentToExpressPath(dirKey),
+        feature: featureNameFromDir(dirKey),
+        page: pageNameFromDir(dirKey),
+      });
+      return;
+    }
+    if (LAYOUT_RE.test(base)) {
+      const depth = dirKey ? dirKey.split("/").length : 0;
+      layouts.push({ abs, rel, dir: dirKey, depth });
+      return;
+    }
+    if (SOURCE_RE.test(base)) {
+      sources.push({ abs, rel });
+    }
+  });
+
+  layouts.sort((a, b) => a.depth - b.depth);
+  pages.sort((a, b) => a.url.localeCompare(b.url));
+  return { pages, layouts, sources };
+}
+
+/**
+ * @param {string} root
+ * @returns {string[]}
+ */
+export function findClientEnvKeys(root) {
+  /** @type {Set<string>} */
+  const keys = new Set();
+  for (const name of [".env", ".env.local", ".env.production", ".env.development"]) {
+    const abs = path.join(root, name);
+    if (!fs.existsSync(abs)) continue;
+    const text = fs.readFileSync(abs, "utf8");
+    for (const line of text.split(/\r?\n/)) {
+      const m = line.match(/^\s*NEXT_PUBLIC_([A-Za-z0-9_]+)\s*=/);
+      if (m) keys.add(m[1]);
+    }
+  }
+  return [...keys].sort();
+}
+
+export { PAGE_RE, LAYOUT_RE, SOURCE_RE };

package/src/migrate/parse.mjs

@@ -0,0 +1,26 @@
+/**
+ * Next.js / React kaynak dosyalarını Babel ile parse eder (JSX + TS).
+ *
+ * `@babel/parser` opsiyonel peerdır; yoksa `getBabel()` kurulum mesajı fırlatır.
+ */
+import { getBabel } from "./babel.mjs";
+
+/**
+ * @param {string} code
+ * @param {string} [filename]
+ * @returns {import('@babel/types').File}
+ */
+export function parseSource(code, filename = "file.tsx") {
+  const { parse } = getBabel();
+  return parse(code, {
+    sourceType: "module",
+    sourceFilename: filename,
+    plugins: [
+      "jsx",
+      "typescript",
+      "importAttributes",
+      "topLevelAwait",
+    ],
+    errorRecovery: false,
+  });
+}

package/src/migrate/scan.mjs

@@ -0,0 +1,177 @@
+/**
+ * Next App Router envanteri + engel listesi.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import {
+  findAppDir,
+  findNextConfig,
+  inventoryApp,
+  findClientEnvKeys,
+  walkFiles,
+} from "./fs-walk.mjs";
+import { ensureBabel } from "./babel.mjs";
+import { classifySource } from "./classify.mjs";
+
+/**
+ * @param {string} root
+ * @returns {object}
+ */
+export function scanProject(root) {
+  // Babel yoksa yüzlerce "parse error" yerine tek net kurulum mesajı.
+  ensureBabel(root);
+
+  const appDir = findAppDir(root);
+  const nextConfig = findNextConfig(root);
+  const clientEnv = findClientEnvKeys(root);
+
+  if (!appDir) {
+    return {
+      root,
+      appDir: null,
+      nextConfig,
+      clientEnv,
+      pages: [],
+      layouts: [],
+      clients: [],
+      components: [],
+      blockers: [
+        {
+          kind: "no-app-dir",
+          message: "No app/ or src/app/ directory found (App Router required).",
+        },
+      ],
+      pagesRouter: fs.existsSync(path.join(root, "pages")),
+    };
+  }
+
+  const inv = inventoryApp(appDir);
+  /** @type {object[]} */
+  const pages = [];
+  /** @type {object[]} */
+  const clients = [];
+  /** @type {object[]} */
+  const components = [];
+  /** @type {object[]} */
+  const blockers = [];
+
+  if (fs.existsSync(path.join(root, "pages"))) {
+    blockers.push({
+      kind: "pages-router",
+      message: "pages/ directory present — Pages Router is out of scope for this codemod.",
+    });
+  }
+
+  const nestedLayouts = inv.layouts.filter((l) => l.depth > 0);
+  if (nestedLayouts.length) {
+    blockers.push({
+      kind: "nested-layouts",
+      message: `${nestedLayouts.length} nested layout(s); JSkelet has a single layout — flatten manually.`,
+      files: nestedLayouts.map((l) => l.rel),
+    });
+  }
+
+  for (const page of inv.pages) {
+    const code = fs.readFileSync(page.abs, "utf8");
+    const classification = classifySource(code, page.rel);
+    pages.push({ ...page, classification });
+    if (classification.hasServerAction) {
+      blockers.push({
+        kind: "server-action",
+        file: page.rel,
+        message: "Server Actions have no equivalent — use app.post handlers.",
+      });
+    }
+    if (classification.hasSuspense) {
+      blockers.push({
+        kind: "suspense",
+        file: page.rel,
+        message: "Suspense / streaming is not supported — use fragment endpoints.",
+      });
+    }
+  }
+
+  for (const layout of inv.layouts) {
+    const code = fs.readFileSync(layout.abs, "utf8");
+    layout.classification = classifySource(code, layout.rel);
+  }
+
+  for (const src of inv.sources) {
+    const code = fs.readFileSync(src.abs, "utf8");
+    const classification = classifySource(code, src.rel);
+    if (classification.kind === "client" || classification.isClient) {
+      clients.push({ ...src, classification });
+    } else if (classification.kind === "server-component") {
+      components.push({ ...src, classification });
+    }
+  }
+
+  for (const dir of ["components", "src/components", "lib/components"]) {
+    const abs = path.join(root, dir);
+    if (!fs.existsSync(abs)) continue;
+    walkFiles(abs, (_rel, fileAbs) => {
+      if (!/\.(jsx?|tsx?)$/.test(fileAbs)) return;
+      const fromRoot = path.relative(root, fileAbs).replace(/\\/g, "/");
+      const code = fs.readFileSync(fileAbs, "utf8");
+      const classification = classifySource(code, fromRoot);
+      if (classification.kind === "client" || classification.isClient) {
+        clients.push({ abs: fileAbs, rel: fromRoot, classification });
+      } else if (classification.kind === "server-component") {
+        components.push({ abs: fileAbs, rel: fromRoot, classification });
+      }
+    });
+  }
+
+  return {
+    root,
+    appDir: path.relative(root, appDir).replace(/\\/g, "/"),
+    nextConfig: nextConfig ? path.relative(root, nextConfig).replace(/\\/g, "/") : null,
+    clientEnv,
+    pages,
+    layouts: inv.layouts,
+    clients,
+    components,
+    blockers,
+    pagesRouter: fs.existsSync(path.join(root, "pages")),
+  };
+}
+
+/**
+ * İnsan-okur özet.
+ * @param {ReturnType<typeof scanProject>} report
+ * @returns {string}
+ */
+export function formatScanReport(report) {
+  const lines = [];
+  lines.push(`Next.js → JSkelet scan`);
+  lines.push(`  app: ${report.appDir ?? "(missing)"}`);
+  lines.push(`  config: ${report.nextConfig ?? "(none)"}`);
+  lines.push(`  pages: ${report.pages.length}`);
+  lines.push(`  layouts: ${report.layouts.length}`);
+  lines.push(`  client modules: ${report.clients.length}`);
+  lines.push(`  server components: ${report.components.length}`);
+  if (report.clientEnv.length) {
+    lines.push(`  NEXT_PUBLIC_* → clientEnv candidates: ${report.clientEnv.join(", ")}`);
+  }
+  if (report.pages.length) {
+    lines.push("");
+    lines.push("Pages:");
+    for (const p of report.pages) {
+      const flags = [];
+      if (p.classification?.revalidate != null) flags.push(`revalidate=${p.classification.revalidate}`);
+      if (p.classification?.hasGenerateMetadata) flags.push("metadata");
+      if (p.classification?.hasGenerateStaticParams) flags.push("staticParams");
+      lines.push(`  ${p.url}  ←  ${p.rel}${flags.length ? `  (${flags.join(", ")})` : ""}`);
+    }
+  }
+  if (report.blockers.length) {
+    lines.push("");
+    lines.push("Blockers:");
+    for (const b of report.blockers) {
+      lines.push(`  ⚠ ${b.message}${b.file ? ` [${b.file}]` : ""}`);
+    }
+  }
+  lines.push("");
+  lines.push("Next: jskelet migrate apply [--write]  |  jskelet migrate config [--write]");
+  return lines.join("\n");
+}

package/src/migrate/transform/expr-source.mjs

@@ -0,0 +1,168 @@
+/**
+ * Babel ifade → kaynak metin + JSK parseExpr doğrulaması.
+ * `@babel/generator` yok; JSX attr / {{ }} için yeterli alt küme basılır.
+ */
+import { t } from "../babel.mjs";
+import { parseExpr } from "../../compile/expr.js";
+
+/**
+ * @param {import('@babel/types').Node} node
+ * @returns {string}
+ */
+export function exprToSource(node) {
+  if (t.isTSAsExpression(node) || t.isTSTypeAssertion(node) || t.isTSNonNullExpression(node)) {
+    return exprToSource(/** @type {{ expression: import('@babel/types').Expression }} */ (node).expression);
+  }
+  if (t.isParenthesizedExpression(node)) {
+    return `(${exprToSource(node.expression)})`;
+  }
+  if (t.isIdentifier(node)) return node.name;
+  if (t.isStringLiteral(node)) return JSON.stringify(node.value);
+  if (t.isNumericLiteral(node)) return String(node.value);
+  if (t.isBooleanLiteral(node)) return node.value ? "true" : "false";
+  if (t.isNullLiteral(node)) return "null";
+  if (t.isBigIntLiteral(node)) return node.value + "n";
+
+  if (t.isMemberExpression(node) || t.isOptionalMemberExpression(node)) {
+    const obj = exprToSource(node.object);
+    const opt = "optional" in node && node.optional ? "?." : ".";
+    if (node.computed) {
+      return `${obj}${opt === "?." ? "?." : ""}[${exprToSource(/** @type {import('@babel/types').Expression} */ (node.property))}]`;
+    }
+    if (t.isIdentifier(node.property)) {
+      return `${obj}${opt}${node.property.name}`;
+    }
+    return `${obj}.${exprToSource(node.property)}`;
+  }
+
+  if (t.isUnaryExpression(node)) {
+    return `${node.operator}${exprToSource(node.argument)}`;
+  }
+
+  if (t.isBinaryExpression(node) || t.isLogicalExpression(node)) {
+    return `${exprToSource(/** @type {import('@babel/types').Expression} */ (node.left))} ${node.operator} ${exprToSource(node.right)}`;
+  }
+
+  if (t.isConditionalExpression(node)) {
+    return `${exprToSource(node.test)} ? ${exprToSource(node.consequent)} : ${exprToSource(node.alternate)}`;
+  }
+
+  if (t.isTemplateLiteral(node)) {
+    let out = "`";
+    for (let i = 0; i < node.quasis.length; i++) {
+      out += node.quasis[i].value.cooked ?? node.quasis[i].value.raw;
+      if (i < node.expressions.length) {
+        out += "${" + exprToSource(node.expressions[i]) + "}";
+      }
+    }
+    return out + "`";
+  }
+
+  if (t.isArrayExpression(node)) {
+    return `[${node.elements.map((el) => (el ? exprToSource(el) : "")).join(", ")}]`;
+  }
+
+  if (t.isObjectExpression(node)) {
+    const props = node.properties.map((p) => {
+      if (t.isSpreadElement(p)) return `...${exprToSource(p.argument)}`;
+      if (t.isObjectMethod(p)) return `/* method */`;
+      if (t.isObjectProperty(p)) {
+        const key = t.isIdentifier(p.key) && !p.computed ? p.key.name : exprToSource(p.key);
+        return `${key}: ${exprToSource(/** @type {import('@babel/types').Expression} */ (p.value))}`;
+      }
+      return "";
+    });
+    return `{ ${props.join(", ")} }`;
+  }
+
+  if (t.isCallExpression(node)) {
+    const callee = exprToSource(node.callee);
+    const args = node.arguments.map((a) => exprToSource(/** @type {import('@babel/types').Node} */ (a))).join(", ");
+    return `${callee}(${args})`;
+  }
+
+  if (t.isAwaitExpression(node)) {
+    return `await ${exprToSource(node.argument)}`;
+  }
+
+  if (t.isArrowFunctionExpression(node) || t.isFunctionExpression(node)) {
+    return `/* function */`;
+  }
+
+  if (t.isThisExpression(node)) return "this";
+
+  return `/* unsupported:${node.type} */`;
+}
+
+/**
+ * @param {string} source
+ * @returns {boolean}
+ */
+export function isJskExpr(source) {
+  if (!source || source.includes("/* unsupported")) return false;
+  try {
+    parseExpr(source);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {import('@babel/types').Expression} expr
+ * @returns {{ ok: true, source: string } | { ok: false, reason: string }}
+ */
+export function tryJskExpr(expr) {
+  if (t.isStringLiteral(expr)) {
+    return { ok: true, source: JSON.stringify(expr.value) };
+  }
+  if (t.isNumericLiteral(expr)) {
+    return { ok: true, source: String(expr.value) };
+  }
+  if (t.isBooleanLiteral(expr)) {
+    return { ok: true, source: expr.value ? "true" : "false" };
+  }
+  if (t.isNullLiteral(expr)) {
+    return { ok: true, source: "null" };
+  }
+
+  const source = exprToSource(expr);
+  if (isJskExpr(source)) return { ok: true, source };
+  return { ok: false, reason: `expression not valid in .jsk: ${source}` };
+}
+
+/**
+ * @param {import('@babel/types').Expression} expr
+ * @param {Set<string>} out
+ */
+export function collectRootIdents(expr, out) {
+  if (t.isIdentifier(expr)) {
+    out.add(expr.name);
+    return;
+  }
+  if (t.isMemberExpression(expr) || t.isOptionalMemberExpression(expr)) {
+    collectRootIdents(/** @type {import('@babel/types').Expression} */ (expr.object), out);
+    return;
+  }
+  if (t.isConditionalExpression(expr)) {
+    collectRootIdents(expr.test, out);
+    collectRootIdents(expr.consequent, out);
+    collectRootIdents(expr.alternate, out);
+    return;
+  }
+  if (t.isLogicalExpression(expr) || t.isBinaryExpression(expr)) {
+    collectRootIdents(/** @type {import('@babel/types').Expression} */ (expr.left), out);
+    collectRootIdents(expr.right, out);
+    return;
+  }
+  if (t.isUnaryExpression(expr)) {
+    collectRootIdents(expr.argument, out);
+    return;
+  }
+  if (t.isCallExpression(expr)) {
+    collectRootIdents(/** @type {import('@babel/types').Expression} */ (expr.callee), out);
+    for (const arg of expr.arguments) {
+      if (t.isExpression(arg)) collectRootIdents(arg, out);
+    }
+  }
+}

package/src/migrate/transform/island.mjs

@@ -0,0 +1,67 @@
+/**
+ * `"use client"` → island `mount()` iskeleti.
+ */
+import path from "node:path";
+
+/**
+ * @typedef {{ status: 'ok' | 'partial' | 'skipped', notes: string[], code: string | null, islandName: string }} IslandResult
+ */
+
+/**
+ * @param {string} code
+ * @param {string} filename
+ * @param {{ name?: string }} [options]
+ * @returns {IslandResult}
+ */
+export function transformIsland(code, filename, options = {}) {
+  const base = path.basename(filename).replace(/\.(jsx?|tsx?|mjs|cjs)$/, "");
+  const islandName = options.name ?? camel(base);
+  /** @type {IslandResult} */
+  const result = {
+    status: "partial",
+    notes: [],
+    code: null,
+    islandName,
+  };
+
+  const hasHooks = /\buse(State|Effect|Memo|Callback|Ref|Context|Reducer)\s*\(/.test(code);
+  if (hasHooks) {
+    result.notes.push("hooks require a manual port into mount()");
+  }
+  if (!/["']use client["']/.test(code) && !hasHooks) {
+    result.notes.push("no \"use client\" directive — treating as island candidate anyway");
+  }
+
+  result.code =
+    `/**\n` +
+    ` * Island migrated from ${filename.replace(/\\/g, "/")}\n` +
+    ` * Register: registerAll({ ${islandName}: () => import("./${islandName}.js") })\n` +
+    ` * Markup: <div data-island="${islandName}" data-island-props='{}'></div>\n` +
+    ` */\n` +
+    `/**\n` +
+    ` * @param {HTMLElement} el\n` +
+    ` * @param {Record<string, unknown>} [props]\n` +
+    ` */\n` +
+    `export function mount(el, props = {}) {\n` +
+    `  // TODO[jskelet-migrate]: port client logic from ${path.basename(filename)}\n` +
+    (hasHooks
+      ? `  // Original file used React hooks — rewrite with plain DOM + events.\n`
+      : "") +
+    `  el.textContent = "";\n` +
+    `  void props;\n` +
+    `}\n`;
+
+  return result;
+}
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+function camel(name) {
+  return name
+    .split(/[-_/]+/)
+    .filter(Boolean)
+    .map((p, i) => (i === 0 ? p.toLowerCase() : p.charAt(0).toUpperCase() + p.slice(1)))
+    .join("");
+}