@mandujs/core 0.24.0 → 0.25.1

package/src/content/slug.ts

@@ -0,0 +1,110 @@
+/**
+ * Slug Utility (Issue #199)
+ *
+ * Converts a file path (relative to a collection root) into a stable
+ * URL-safe slug. This powers `collection.get(slug)` lookups and the
+ * default href generation in `generateSidebar()`.
+ *
+ * # Algorithm
+ *
+ *   1. Normalize separators: Windows backslashes → forward slashes so
+ *      slugs are portable across platforms
+ *   2. Strip the file extension
+ *   3. Drop an `index` basename: `docs/intro/index.md` → `docs/intro`
+ *      so authors can use index-style directories without a dangling
+ *      `/index` suffix in URLs
+ *   4. Optional: kebab-case each segment (default ON) so file names
+ *      like `Getting_Started.md` produce `getting-started`
+ *   5. Remove any consecutive slashes and leading/trailing slashes
+ */
+
+/** Options controlling slug generation. */
+export interface SlugFromPathOptions {
+  /**
+   * When true (default), every path segment is lower-cased and
+   * underscores/camelCase boundaries are converted to dashes.
+   * Disable this when a project's authoring convention requires
+   * preserving source file naming — in which case only the
+   * extension and `/index` suffix are stripped.
+   */
+  kebabCase?: boolean;
+  /**
+   * Extra extensions to strip, in addition to the defaults
+   * (`.md`, `.mdx`, `.markdown`). Caller-supplied values should
+   * include the leading dot.
+   */
+  stripExtensions?: string[];
+  /**
+   * Override the default "drop `/index` suffix" behavior. When
+   * false, `foo/index.md` becomes `foo/index` instead of `foo`.
+   */
+  dropIndex?: boolean;
+}
+
+const DEFAULT_EXTS = new Set([".md", ".mdx", ".markdown"]);
+
+/**
+ * Convert a collection-relative path to a URL slug.
+ *
+ * @example
+ * ```ts
+ * slugFromPath("getting-started/install.md") // "getting-started/install"
+ * slugFromPath("Intro\\Welcome.md")          // "intro/welcome"
+ * slugFromPath("api/index.md")               // "api"
+ * slugFromPath("API_v2.md", { kebabCase: false }) // "API_v2"
+ * ```
+ */
+export function slugFromPath(
+  filePath: string,
+  options: SlugFromPathOptions = {}
+): string {
+  const { kebabCase = true, stripExtensions, dropIndex = true } = options;
+  const allExts = new Set<string>(DEFAULT_EXTS);
+  if (stripExtensions) {
+    for (const ext of stripExtensions) allExts.add(ext);
+  }
+
+  // Normalize separators first so downstream logic only deals with `/`.
+  let out = filePath.replace(/\\/g, "/").trim();
+
+  // Strip any matching extension from the tail. We only strip ONE —
+  // files with double extensions (`foo.test.md`) keep the `.test`
+  // segment on purpose.
+  const dotIdx = out.lastIndexOf(".");
+  const slashIdx = out.lastIndexOf("/");
+  if (dotIdx > slashIdx) {
+    const ext = out.slice(dotIdx);
+    if (allExts.has(ext.toLowerCase())) {
+      out = out.slice(0, dotIdx);
+    }
+  }
+
+  // Drop `/index` suffix or a bare `index` basename.
+  if (dropIndex) {
+    if (out === "index") {
+      out = "";
+    } else if (out.endsWith("/index")) {
+      out = out.slice(0, -"/index".length);
+    }
+  }
+
+  // kebab-case per segment so existing slashes survive.
+  if (kebabCase) {
+    out = out
+      .split("/")
+      .map((seg) =>
+        seg
+          // Insert dash between camelCase: fooBar → foo-Bar (later lower-cased)
+          .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+          .replace(/[_\s]+/g, "-")
+          .replace(/--+/g, "-")
+          .toLowerCase()
+      )
+      .join("/");
+  }
+
+  // Collapse duplicate slashes and strip boundary slashes.
+  out = out.replace(/\/+/g, "/").replace(/^\/+|\/+$/g, "");
+
+  return out;
+}

package/src/guard/check.ts

@@ -119,9 +119,12 @@ export async function checkInvalidGeneratedImport(
         violations.push({
           ruleId: GUARD_RULES.INVALID_GENERATED_IMPORT.id,
           file: relativePath,
-          message: `generated 파일 직접 import 금지: ${match[1]}`,
+          message:
+            `Direct __generated__/ imports are forbidden: ${match[1]}. ` +
+            `Use the runtime registry: see https://mandujs.com/docs/architect/generated-access`,
           suggestion:
-            "generated 파일을 직접 import하지 말고, 런타임 레지스트리를 통해 접근하세요",
+            "Import getGenerated() from @mandujs/core/runtime and read the generated artifact through the manifest. " +
+            "See https://mandujs.com/docs/architect/generated-access for the decision tree.",
         });
       }
     }

package/src/observability/index.ts

@@ -1,18 +1,37 @@
-export {
-  eventBus,
-  type ObservabilityEvent,
-  type EventType,
-  type ObservabilitySeverity,
-  type EventHandler,
-} from "./event-bus";
-export { connectLoggerToEventBus } from "./logger-adapter";
-// Phase 6: SQLite 영구 저장 + 시계열 쿼리
-export {
-  startSqliteStore,
-  stopSqliteStore,
-  queryEvents,
-  queryStats,
-  exportJsonl,
-  exportOtlp,
-  type QueryOptions,
-} from "./sqlite-store";
+export {
+  eventBus,
+  type ObservabilityEvent,
+  type EventType,
+  type ObservabilitySeverity,
+  type EventHandler,
+} from "./event-bus";
+export { connectLoggerToEventBus } from "./logger-adapter";
+// Phase 6: SQLite 영구 저장 + 시계열 쿼리
+export {
+  startSqliteStore,
+  stopSqliteStore,
+  queryEvents,
+  queryStats,
+  exportJsonl,
+  exportOtlp,
+  type QueryOptions,
+} from "./sqlite-store";
+// Phase 17: heap endpoint + Prometheus metrics
+export {
+  registerCacheSize,
+  unregisterCacheSize,
+  clearCacheSizeReporters,
+  collectCacheSizes,
+  recordHttpRequest,
+  resetHttpRequestCounter,
+  getHttpRequestCounts,
+  collectHeapSnapshot,
+  renderPrometheus,
+  isObservabilityExposed,
+  buildHeapResponse,
+  buildMetricsResponse,
+  HEAP_ENDPOINT,
+  METRICS_ENDPOINT,
+  type HeapSnapshot,
+  type CacheName,
+} from "./metrics";

package/src/observability/metrics.ts

@@ -0,0 +1,334 @@
+/**
+ * Phase 17 — lightweight in-process metrics + heap snapshot.
+ *
+ * Two outputs are derived from the same underlying state:
+ *
+ *   1. JSON snapshot (`/_mandu/heap`) — human-oriented debug dump.
+ *   2. Prometheus text exposition (`/_mandu/metrics`) — scraper-friendly.
+ *
+ * Design rules:
+ *   - Hand-rolled. No new runtime deps.
+ *   - Zero allocation in the hot path — counters are plain numbers.
+ *   - Cache sizes are provided through a registry so each cache lives
+ *     in its own module (no circular imports). Call
+ *     `registerCacheSize("patternCache", () => cache.size)` at module
+ *     init; the metrics collector calls each reporter lazily on scrape.
+ *   - Label cardinality is strictly bounded — HTTP request counts are
+ *     keyed by `{method, statusClass}` where statusClass is `2xx`/`3xx`/
+ *     `4xx`/`5xx`/`other`, not the raw status. Prevents runaway series.
+ */
+
+export type CacheName = "patternCache" | "fetchCache" | "perFileTimers" | string;
+
+/**
+ * Registry of cache-size reporters. Each reporter is called at scrape
+ * time and must return the current cache entry count. Reporters that
+ * throw or return a non-finite number are treated as `0` (defence
+ * against a half-torn-down subsystem).
+ */
+const cacheSizeReporters = new Map<CacheName, () => number>();
+
+/**
+ * Register (or replace) a cache-size reporter. Callers typically wire
+ * this at module init:
+ *
+ *   const cache = new LRUCache<string, Compiled>({ maxSize: 200 });
+ *   registerCacheSize("patternCache", () => cache.size);
+ */
+export function registerCacheSize(name: CacheName, reporter: () => number): void {
+  cacheSizeReporters.set(name, reporter);
+}
+
+/**
+ * Unregister a reporter. Used by hot-reload paths that rebuild their
+ * cache under a fresh reference.
+ */
+export function unregisterCacheSize(name: CacheName): boolean {
+  return cacheSizeReporters.delete(name);
+}
+
+/**
+ * For tests — drop every reporter. Production code should never need this.
+ */
+export function clearCacheSizeReporters(): void {
+  cacheSizeReporters.clear();
+}
+
+/**
+ * Collect current sizes. Missing reporters simply don't appear. A
+ * thrown / non-finite reporter contributes `0` and is silently logged
+ * on the event bus (best-effort — we never propagate).
+ */
+export function collectCacheSizes(): Record<string, number> {
+  const out: Record<string, number> = {};
+  for (const [name, reporter] of cacheSizeReporters) {
+    let size = 0;
+    try {
+      const v = reporter();
+      size = typeof v === "number" && Number.isFinite(v) ? Math.max(0, Math.floor(v)) : 0;
+    } catch {
+      size = 0;
+    }
+    out[name] = size;
+  }
+  return out;
+}
+
+// --------------------------------------------------------------------
+// HTTP request counter
+// --------------------------------------------------------------------
+
+/**
+ * `Map` keyed by `"METHOD statusClass"` for bounded cardinality.
+ * E.g. `"GET 2xx"` → 41.
+ */
+const httpRequestCounter = new Map<string, number>();
+
+const STATUS_CLASSES = ["2xx", "3xx", "4xx", "5xx", "other"] as const;
+type StatusClass = (typeof STATUS_CLASSES)[number];
+
+function classifyStatus(status: number): StatusClass {
+  if (status >= 200 && status < 300) return "2xx";
+  if (status >= 300 && status < 400) return "3xx";
+  if (status >= 400 && status < 500) return "4xx";
+  if (status >= 500 && status < 600) return "5xx";
+  return "other";
+}
+
+function normalizeMethod(method: string | undefined): string {
+  if (!method) return "UNKNOWN";
+  const upper = method.toUpperCase();
+  // Whitelist standard methods so a rogue "evil\n" header can't break
+  // the Prometheus line format. Anything unknown bucket under OTHER.
+  const allowed = new Set([
+    "GET",
+    "HEAD",
+    "POST",
+    "PUT",
+    "DELETE",
+    "PATCH",
+    "OPTIONS",
+    "TRACE",
+    "CONNECT",
+  ]);
+  return allowed.has(upper) ? upper : "OTHER";
+}
+
+/**
+ * Bump the request counter. Safe to call on every request path — O(1).
+ * The method/status pair is normalised to a bounded cardinality set.
+ */
+export function recordHttpRequest(method: string | undefined, status: number): void {
+  const m = normalizeMethod(method);
+  const cls = classifyStatus(status);
+  const key = `${m} ${cls}`;
+  httpRequestCounter.set(key, (httpRequestCounter.get(key) ?? 0) + 1);
+}
+
+/** Reset counters. Used by tests; prod rarely needs this. */
+export function resetHttpRequestCounter(): void {
+  httpRequestCounter.clear();
+}
+
+/** Snapshot current counts for programmatic inspection. */
+export function getHttpRequestCounts(): Array<{ method: string; statusClass: StatusClass; value: number }> {
+  const out: Array<{ method: string; statusClass: StatusClass; value: number }> = [];
+  for (const [key, value] of httpRequestCounter) {
+    const [method, statusClass] = key.split(" ");
+    out.push({ method: method!, statusClass: statusClass as StatusClass, value });
+  }
+  // Stable order → deterministic Prometheus output (aids scraping + tests).
+  out.sort((a, b) => {
+    if (a.method !== b.method) return a.method < b.method ? -1 : 1;
+    return a.statusClass < b.statusClass ? -1 : 1;
+  });
+  return out;
+}
+
+// --------------------------------------------------------------------
+// Heap snapshot
+// --------------------------------------------------------------------
+
+export interface HeapSnapshot {
+  /** Unix epoch millis when snapshot was captured. */
+  timestamp: number;
+  /** Process uptime in seconds. */
+  uptime: number;
+  /** `process.memoryUsage()` — always available. */
+  process: {
+    rss: number;
+    heapTotal: number;
+    heapUsed: number;
+    external: number;
+    arrayBuffers: number;
+  };
+  /** `Bun.memoryUsage()` if running on Bun and the API is available. */
+  bun?: Record<string, number>;
+  /** Current cache entry counts, keyed by reporter name. */
+  caches: Record<string, number>;
+}
+
+/**
+ * Assemble a heap snapshot. This is the single source of truth for
+ * both the JSON endpoint and the Prometheus exporter.
+ */
+export function collectHeapSnapshot(): HeapSnapshot {
+  const mem = process.memoryUsage();
+  const snapshot: HeapSnapshot = {
+    timestamp: Date.now(),
+    uptime: process.uptime(),
+    process: {
+      rss: mem.rss,
+      heapTotal: mem.heapTotal,
+      heapUsed: mem.heapUsed,
+      external: mem.external,
+      arrayBuffers: mem.arrayBuffers ?? 0,
+    },
+    caches: collectCacheSizes(),
+  };
+
+  // Bun.memoryUsage() is currently a non-standard helper; we feature-
+  // detect to stay forward-compatible with other runtimes (Node tests,
+  // edge workers) where the global is absent.
+  const bunGlobal = (globalThis as { Bun?: { memoryUsage?: () => Record<string, number> } }).Bun;
+  if (bunGlobal?.memoryUsage) {
+    try {
+      const bunMem = bunGlobal.memoryUsage();
+      if (bunMem && typeof bunMem === "object") {
+        snapshot.bun = bunMem;
+      }
+    } catch {
+      // Swallow — not every Bun version ships this.
+    }
+  }
+
+  return snapshot;
+}
+
+// --------------------------------------------------------------------
+// Prometheus text exposition
+// --------------------------------------------------------------------
+
+/**
+ * Escape a label value per Prometheus text format §
+ *
+ *   - backslash → `\\`
+ *   - newline → `\n`
+ *   - double-quote → `\"`
+ *
+ * We never inline tab/CR because `normalizeMethod` already clamps
+ * methods to uppercase ASCII and statusClass is a fixed enum.
+ */
+function escapeLabelValue(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, '\\"');
+}
+
+/**
+ * Render the current metric state in Prometheus text format. Each
+ * metric starts with `# HELP` + `# TYPE` headers per the spec.
+ *
+ * The output is deterministic (sorted labels, stable order) so tests
+ * can snapshot against it and scrapers get a consistent diff.
+ */
+export function renderPrometheus(snapshot?: HeapSnapshot): string {
+  const snap = snapshot ?? collectHeapSnapshot();
+  const lines: string[] = [];
+
+  // Node/Bun heap gauges.
+  lines.push(
+    "# HELP nodejs_heap_used_bytes Process heap used in bytes (process.memoryUsage().heapUsed).",
+    "# TYPE nodejs_heap_used_bytes gauge",
+    `nodejs_heap_used_bytes ${snap.process.heapUsed}`,
+    "# HELP nodejs_heap_total_bytes Process heap total in bytes (process.memoryUsage().heapTotal).",
+    "# TYPE nodejs_heap_total_bytes gauge",
+    `nodejs_heap_total_bytes ${snap.process.heapTotal}`,
+    "# HELP nodejs_external_bytes Process external memory in bytes (process.memoryUsage().external).",
+    "# TYPE nodejs_external_bytes gauge",
+    `nodejs_external_bytes ${snap.process.external}`,
+    "# HELP nodejs_rss_bytes Process resident set size in bytes.",
+    "# TYPE nodejs_rss_bytes gauge",
+    `nodejs_rss_bytes ${snap.process.rss}`,
+    "# HELP nodejs_uptime_seconds Process uptime in seconds.",
+    "# TYPE nodejs_uptime_seconds gauge",
+    `nodejs_uptime_seconds ${snap.uptime.toFixed(3)}`,
+  );
+
+  // Cache entry counts — one line per registered reporter. Keys are
+  // emitted in sorted order so the output is stable across scrapes.
+  lines.push(
+    "# HELP mandu_cache_entries Current entry count for Mandu internal caches.",
+    "# TYPE mandu_cache_entries gauge",
+  );
+  const cacheNames = Object.keys(snap.caches).sort();
+  if (cacheNames.length === 0) {
+    // Prometheus requires at least one sample for the series to be
+    // useful; emit a zero-valued placeholder so scrapers don't drop
+    // the metric entirely on an empty registry.
+    lines.push(`mandu_cache_entries{cache="none"} 0`);
+  } else {
+    for (const name of cacheNames) {
+      lines.push(`mandu_cache_entries{cache="${escapeLabelValue(name)}"} ${snap.caches[name]}`);
+    }
+  }
+
+  // HTTP request counter.
+  lines.push(
+    "# HELP mandu_http_requests_total Total HTTP requests served by the Mandu runtime.",
+    "# TYPE mandu_http_requests_total counter",
+  );
+  const counts = getHttpRequestCounts();
+  if (counts.length === 0) {
+    lines.push(`mandu_http_requests_total{method="GET",status="2xx"} 0`);
+  } else {
+    for (const { method, statusClass, value } of counts) {
+      lines.push(
+        `mandu_http_requests_total{method="${escapeLabelValue(method)}",status="${escapeLabelValue(statusClass)}"} ${value}`,
+      );
+    }
+  }
+
+  // Final newline — the Prometheus parser is tolerant but conventional.
+  return lines.join("\n") + "\n";
+}
+
+// --------------------------------------------------------------------
+// HTTP endpoint handlers
+// --------------------------------------------------------------------
+
+/** Endpoint paths used by the runtime dispatcher. */
+export const HEAP_ENDPOINT = "/_mandu/heap";
+export const METRICS_ENDPOINT = "/_mandu/metrics";
+
+/**
+ * Gate production access. In dev (`isDev=true`) we always allow.
+ * In prod the operator must set `MANDU_DEBUG_HEAP=1` (so scrapers
+ * cannot trivially probe) unless an explicit config flag opted in.
+ */
+export function isObservabilityExposed(isDev: boolean, configFlag: boolean | undefined): boolean {
+  if (isDev) return configFlag !== false;
+  if (configFlag === true) return true;
+  return process.env.MANDU_DEBUG_HEAP === "1";
+}
+
+export function buildHeapResponse(): Response {
+  const snapshot = collectHeapSnapshot();
+  return new Response(JSON.stringify(snapshot, null, 2), {
+    status: 200,
+    headers: {
+      "Content-Type": "application/json; charset=utf-8",
+      "Cache-Control": "no-store",
+    },
+  });
+}
+
+export function buildMetricsResponse(): Response {
+  const body = renderPrometheus();
+  return new Response(body, {
+    status: 200,
+    headers: {
+      // Prometheus text exposition format spec version 0.0.4.
+      "Content-Type": "text/plain; version=0.0.4; charset=utf-8",
+      "Cache-Control": "no-store",
+    },
+  });
+}

package/src/runtime/index.ts

@@ -29,3 +29,14 @@ export { type MiddlewareContext, type MiddlewareNext, type MiddlewareFn, type Mi
 export { type ManduAdapter, type AdapterOptions, type AdapterServer } from "./adapter";
 export { adapterBun } from "./adapter-bun";
 export { createFetchHandler, type FetchHandlerOptions } from "./handler";
+export {
+  getGenerated,
+  tryGetGenerated,
+  getManifest,
+  getRouteById,
+  registerManifest,
+  clearGeneratedRegistry,
+  type GeneratedRegistry,
+  type GeneratedKey,
+  type GeneratedShape,
+} from "./registry";