@ozsarman/clarityjs 0.6.0

package/src/sourcemap.js

@@ -0,0 +1,130 @@
+/**
+ * Clarity.js Source Map Generator
+ *
+ * Produces V3 source maps that map generated JS lines back to .clarity source.
+ * The codegen embeds "//@ SM:N" marker comments at key points.
+ * This module strips those markers and builds the final source map.
+ *
+ * V3 source map format: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/
+ *
+ * Author: Claude (Anthropic)
+ */
+
+// ─── VLQ Encoding ─────────────────────────────────────────────────────────────
+// Base64 alphabet
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+/**
+ * Encode a single signed integer as VLQ.
+ * Each digit is 5 bits; the high bit is a "continue" flag.
+ * The lowest bit of the first digit encodes the sign.
+ */
+function vlqEncode(n) {
+  // Convert to sign-magnitude VLQ format
+  let vlq = n < 0 ? ((-n) << 1) | 1 : (n << 1);
+  let out = '';
+  do {
+    let digit = vlq & 0x1F;          // take 5 bits
+    vlq >>>= 5;
+    if (vlq > 0) digit |= 0x20;      // set continuation bit
+    out += B64[digit];
+  } while (vlq > 0);
+  return out;
+}
+
+/**
+ * Encode an array of segments (one generated line's mappings).
+ * Each segment is [genCol, srcFileIdx, srcLine, srcCol] (all 0-indexed, relative).
+ */
+function encodeSegments(segments) {
+  let out = '';
+  let prevGenCol = 0, prevSrcFile = 0, prevSrcLine = 0, prevSrcCol = 0;
+
+  for (const [genCol, srcFile, srcLine, srcCol] of segments) {
+    out += vlqEncode(genCol - prevGenCol);
+    out += vlqEncode(srcFile - prevSrcFile);
+    out += vlqEncode(srcLine - prevSrcLine);
+    out += vlqEncode(srcCol - prevSrcCol);
+    prevGenCol = genCol;
+    prevSrcFile = srcFile;
+    prevSrcLine = srcLine;
+    prevSrcCol = srcCol;
+  }
+  return out;
+}
+
+// ─── Source Map Builder ───────────────────────────────────────────────────────
+
+/**
+ * Process code that contains "//@ SM:N" marker lines.
+ *
+ * The codegen embeds these markers right before lines that trace to source line N.
+ * This function:
+ *   1. Strips all SM markers from the code
+ *   2. Uses them to build a V3 source map (line-level precision)
+ *   3. Optionally inlines the source map as a data URL
+ *
+ * Returns: { code, map } where map is the V3 source map object.
+ */
+export function processSourceMarkers(annotatedCode, options = {}) {
+  const {
+    filename     = '<anonymous>',  // output .js filename
+    sourceFile   = '<source>',     // input .clarity filename
+    sourceContent = '',            // input source text (for sourcesContent)
+    inline       = true,           // embed map as data URL at bottom of code
+  } = options;
+
+  const MARKER_RE = /^\s*\/\/@ SM:(\d+)\s*$/;  // allow indented markers
+  const inputLines  = annotatedCode.split('\n');
+  const cleanLines  = [];   // output lines (markers removed)
+  const lineMappings = [];  // cleanLine index → source line (1-indexed), -1 = no mapping
+
+  let currentSrcLine = -1;  // last seen SM marker value
+
+  for (const line of inputLines) {
+    const m = line.match(MARKER_RE);
+    if (m) {
+      currentSrcLine = parseInt(m[1], 10);
+      // Don't emit marker line to output
+    } else {
+      cleanLines.push(line);
+      lineMappings.push(currentSrcLine);
+    }
+  }
+
+  // ── Build V3 mappings string ────────────────────────────────────────────────
+  // For each output line, emit one segment (column 0 mapped to source line).
+  // Lines with no mapping emit an empty group.
+  const mappingGroups = lineMappings.map((srcLine) => {
+    if (srcLine < 0) return '';
+    // Segment: [genCol=0, srcFile=0, srcLine (0-indexed), srcCol=0]
+    return encodeSegments([[0, 0, srcLine - 1, 0]]);
+  });
+
+  const map = {
+    version: 3,
+    file: filename,
+    sourceRoot: '',
+    sources: [sourceFile],
+    sourcesContent: [sourceContent],
+    mappings: mappingGroups.join(';'),
+  };
+
+  const cleanCode = cleanLines.join('\n');
+
+  if (inline) {
+    const b64 = Buffer.from(JSON.stringify(map)).toString('base64');
+    const annotated = cleanCode + `\n//# sourceMappingURL=data:application/json;base64,${b64}`;
+    return { code: annotated, map };
+  }
+
+  return { code: cleanCode, map };
+}
+
+/**
+ * Write a .map sidecar file for a given JS file.
+ * Usage: writeMapFile('/path/to/out.js', map)
+ */
+export function buildMapComment(mapFilename) {
+  return `//# sourceMappingURL=${mapFilename}`;
+}

package/src/ssg.js

@@ -0,0 +1,310 @@
+/**
+ * Clarity.js — Static Site Generation (SSG)
+ *
+ * Build-time HTML üretimi. Next.js getStaticProps / Nuxt generate eşdeğeri.
+ *
+ * ── Kullanım (pages/ konvansiyonu ile) ───────────────────────────────────────
+ *
+ *   // pages/blog/[slug].js
+ *   export default function BlogPost({ slug, post }) { ... }
+ *
+ *   export async function getStaticPaths() {
+ *     const posts = await db.posts.findAll();
+ *     return posts.map(p => ({ params: { slug: p.slug } }));
+ *   }
+ *
+ *   export async function getStaticProps({ params }) {
+ *     const post = await db.posts.findBySlug(params.slug);
+ *     return { props: { post }, revalidate: 3600 };  // ISR için revalidate
+ *   }
+ *
+ * ── CLI kullanımı ─────────────────────────────────────────────────────────────
+ *
+ *   clarity ssg                      # dist/ klasörüne statik HTML üret
+ *   clarity ssg ./my-app --out dist  # özel çıktı klasörü
+ *
+ * ── Programatik kullanım ──────────────────────────────────────────────────────
+ *
+ *   import { generateStaticSite } from '@ozsarman/clarityjs/ssg';
+ *
+ *   await generateStaticSite({
+ *     pagesDir:  './pages',
+ *     outDir:    './dist',
+ *     baseUrl:   'https://mysite.com',
+ *     concurrent: 4,
+ *   });
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+import { readdir, stat, mkdir, writeFile, copyFile, readFile } from 'node:fs/promises';
+import { existsSync, mkdirSync }                               from 'node:fs';
+import { join, relative, extname, basename, dirname, resolve } from 'node:path';
+import { pathToFileURL }                                        from 'node:url';
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Statik site oluştur — pages/ dizinini tarar, her sayfa için HTML üretir.
+ *
+ * @param {object} opts
+ * @param {string}  opts.pagesDir   – sayfa dosyalarının dizini (default: 'pages')
+ * @param {string}  opts.outDir     – HTML çıktı dizini        (default: 'dist')
+ * @param {string}  opts.publicDir  – kopyalanacak statik dosyalar (default: 'public')
+ * @param {string}  [opts.baseUrl]  – canonical URL tabanı
+ * @param {string}  [opts.title]    – varsayılan sayfa başlığı
+ * @param {string}  [opts.clientScript] – client JS bundle yolu (dist/app.js gibi)
+ * @param {number}  [opts.concurrent=4] – eş zamanlı render sayısı
+ * @param {boolean} [opts.verbose]  – ayrıntılı log
+ * @returns {Promise<SSGResult>}
+ */
+export async function generateStaticSite(opts = {}) {
+  const {
+    pagesDir     = 'pages',
+    outDir       = 'dist',
+    publicDir    = 'public',
+    baseUrl      = '',
+    title        = '',
+    clientScript = null,
+    concurrent   = 4,
+    verbose      = false,
+  } = opts;
+
+  const pagesDirAbs  = resolve(pagesDir);
+  const outDirAbs    = resolve(outDir);
+  const publicDirAbs = resolve(publicDir);
+
+  const log = (...args) => verbose && console.log('[clarity/ssg]', ...args);
+  const t0  = Date.now();
+
+  // 1. Çıktı dizinini oluştur
+  await mkdir(outDirAbs, { recursive: true });
+
+  // 2. pages/ altındaki tüm dosyaları tara
+  const pageFiles = await _scanPages(pagesDirAbs);
+  log(`${pageFiles.length} sayfa bulundu`);
+
+  // 3. Her sayfa dosyasını yükle ve statik yolları topla
+  const renderJobs = [];
+
+  for (const file of pageFiles) {
+    const mod       = await import(pathToFileURL(file).href + `?bust=${Date.now()}`);
+    const routePath = _fileToRoutePath(pagesDirAbs, file);
+    const isApiFile = routePath.startsWith('/api/') ||
+      ['GET','POST','PUT','PATCH','DELETE'].some(m => typeof mod[m] === 'function');
+
+    if (isApiFile) continue; // API route'ları dahil etme
+
+    if (typeof mod.getStaticPaths === 'function') {
+      // Dinamik rota — her path için ayrı job
+      const paths = await mod.getStaticPaths();
+      for (const entry of paths) {
+        const params   = entry.params ?? {};
+        const resolved = _resolveRoute(routePath, params);
+        renderJobs.push({ file, mod, routePath: resolved, params, isDynamic: true });
+      }
+    } else {
+      // Statik rota
+      renderJobs.push({ file, mod, routePath, params: {}, isDynamic: false });
+    }
+  }
+
+  log(`${renderJobs.length} HTML dosyası oluşturulacak`);
+
+  // 4. Paralel render — max `concurrent` eş zamanlı
+  const results   = [];
+  const isr_data  = {};  // revalidate için metadata
+
+  for (let i = 0; i < renderJobs.length; i += concurrent) {
+    const batch = renderJobs.slice(i, i + concurrent);
+    const batch_results = await Promise.all(batch.map(job =>
+      _renderJob(job, { outDirAbs, baseUrl, title, clientScript, log, isr_data })
+    ));
+    results.push(...batch_results);
+  }
+
+  // 5. ISR metadata dosyasını yaz (ISR modülü okur)
+  if (Object.keys(isr_data).length > 0) {
+    await writeFile(
+      join(outDirAbs, '_clarity_isr.json'),
+      JSON.stringify(isr_data, null, 2)
+    );
+    log('ISR metadata yazıldı → _clarity_isr.json');
+  }
+
+  // 6. public/ klasörünü kopyala
+  if (existsSync(publicDirAbs)) {
+    await _copyDir(publicDirAbs, outDirAbs, log);
+  }
+
+  const elapsed = Date.now() - t0;
+  const ok      = results.filter(r => r.success).length;
+  const fail    = results.filter(r => !r.success).length;
+
+  console.log(`[clarity/ssg] ✅ ${ok} sayfa oluşturuldu${fail ? `, ❌ ${fail} hata` : ''} (${elapsed}ms)`);
+
+  return { pages: results, isrData: isr_data, outDir: outDirAbs, elapsed };
+}
+
+// ─── getStaticProps / getStaticPaths helpers ──────────────────────────────────
+
+/**
+ * Tek bir sayfa için statik props çek.
+ * Sayfa dosyasında `export async function getStaticProps({ params })` beklenir.
+ *
+ * @param {string}  file    – sayfa dosyasının mutlak yolu
+ * @param {object}  params  – URL parametreleri (dinamik rotalar için)
+ * @returns {Promise<{ props: object, revalidate?: number, notFound?: boolean }>}
+ */
+export async function fetchStaticProps(file, params = {}) {
+  const mod = await import(pathToFileURL(file).href);
+  if (typeof mod.getStaticProps !== 'function') return { props: {} };
+
+  const result = await mod.getStaticProps({ params });
+  return result ?? { props: {} };
+}
+
+/**
+ * Dinamik rota için statik yolları çek.
+ * Sayfa dosyasında `export async function getStaticPaths()` beklenir.
+ *
+ * @param {string} file – sayfa dosyasının mutlak yolu
+ * @returns {Promise<Array<{ params: object }>>}
+ */
+export async function fetchStaticPaths(file) {
+  const mod = await import(pathToFileURL(file).href);
+  if (typeof mod.getStaticPaths !== 'function') return [];
+  return await mod.getStaticPaths();
+}
+
+// ─── SSG Context helper ───────────────────────────────────────────────────────
+
+/**
+ * Server tarafında SSG context'i oluştur.
+ * Component'ler içinde kullanılabilir (server-side only).
+ *
+ * @param {object} params   – URL parametreleri
+ * @param {object} props    – getStaticProps'tan gelen props
+ * @returns {object}
+ */
+export function createSSGContext(params = {}, props = {}) {
+  return { params, props, isSSG: true, isSSR: false };
+}
+
+// ─── Internal: render tek bir sayfa ──────────────────────────────────────────
+
+async function _renderJob(job, { outDirAbs, baseUrl, title, clientScript, log, isr_data }) {
+  const { file, mod, routePath, params } = job;
+
+  try {
+    // getStaticProps'u çağır
+    let pageProps = params;
+    let revalidate = null;
+    let notFound   = false;
+
+    if (typeof mod.getStaticProps === 'function') {
+      const result = await mod.getStaticProps({ params });
+      if (result?.notFound) {
+        notFound = true;
+      } else {
+        pageProps = { ...params, ...(result?.props ?? {}) };
+        revalidate = result?.revalidate ?? null;
+      }
+    }
+
+    if (notFound) {
+      log(`SKIP (notFound) → ${routePath}`);
+      return { routePath, success: true, notFound: true };
+    }
+
+    // Component'i render et
+    const { renderToDocument } = await import('./ssr.js');
+    const pageTitle = mod.meta?.title ?? title ?? '';
+    const html = renderToDocument(mod.default, {
+      props:        pageProps,
+      title:        pageTitle,
+      clientScript,
+      lang:         'tr',
+      // SSG metadata: initial data gömülü
+      inlineData:   { __SSG_PROPS__: pageProps, __SSG_PATH__: routePath },
+    });
+
+    // Dosya yolunu belirle
+    const filePath = _routeToFilePath(outDirAbs, routePath);
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, html, 'utf8');
+
+    // ISR metadata
+    if (revalidate) {
+      isr_data[routePath] = {
+        revalidate,
+        file:        relative(process.cwd(), file),
+        params,
+        generatedAt: Date.now(),
+        expiresAt:   Date.now() + revalidate * 1000,
+      };
+    }
+
+    log(`✅ ${routePath} → ${relative(outDirAbs, filePath)}`);
+    return { routePath, success: true, filePath, revalidate };
+
+  } catch (err) {
+    console.error(`[clarity/ssg] ❌ ${routePath}: ${err.message}`);
+    return { routePath, success: false, error: err.message };
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+async function _scanPages(dir, files = []) {
+  if (!existsSync(dir)) return files;
+  const entries = await readdir(dir);
+  for (const entry of entries) {
+    if (entry.startsWith('_') || entry.startsWith('.')) continue;
+    const full = join(dir, entry);
+    const info = await stat(full);
+    if (info.isDirectory()) {
+      await _scanPages(full, files);
+    } else if (/\.(js|mjs|clarity)$/.test(entry)) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+function _fileToRoutePath(pagesDir, file) {
+  const rel  = relative(pagesDir, file).replace(/\\/g, '/');
+  const name = rel.replace(/\.(js|mjs|clarity)$/, '');
+  if (name === 'index') return '/';
+  return '/' + name
+    .split('/')
+    .map(seg => seg === 'index' ? '' : seg.replace(/^\[\.\.\.(.+)\]$/, ':$1*').replace(/^\[(.+)\]$/, ':$1'))
+    .filter(Boolean)
+    .join('/');
+}
+
+function _resolveRoute(routePattern, params) {
+  return routePattern.replace(/:(\w+)\*?/g, (_, key) => params[key] ?? `[${key}]`);
+}
+
+function _routeToFilePath(outDir, routePath) {
+  if (routePath === '/') return join(outDir, 'index.html');
+  const clean = routePath.replace(/^\//, '');
+  return join(outDir, clean, 'index.html');
+}
+
+async function _copyDir(src, dest, log) {
+  const entries = await readdir(src);
+  for (const entry of entries) {
+    const srcFull  = join(src, entry);
+    const destFull = join(dest, entry);
+    const info     = await stat(srcFull);
+    if (info.isDirectory()) {
+      await mkdir(destFull, { recursive: true });
+      await _copyDir(srcFull, destFull, log);
+    } else {
+      await copyFile(srcFull, destFull);
+      log(`copy public/ → ${entry}`);
+    }
+  }
+}