specra 0.1.0

package/src/lib/mdx-cache.ts

@@ -0,0 +1,200 @@
+/**
+ * Caching layer for MDX operations to improve development performance
+ *
+ * This module provides in-memory caching for expensive file system operations
+ * that occur during static generation. In development mode, caches are
+ * invalidated automatically when files change.
+ */
+
+import { Doc, getVersions, getAllDocs, getDocBySlug } from './mdx'
+import { watch } from 'fs'
+import { join } from 'path'
+import { PerfTimer, logCacheOperation } from './dev-utils'
+
+const isDevelopment = process.env.NODE_ENV === 'development'
+
+// Cache stores
+const versionsCache = {
+  data: null as string[] | null,
+  timestamp: 0,
+}
+
+const allDocsCache = new Map<string, {
+  data: Doc[]
+  timestamp: number
+}>()
+
+const docBySlugCache = new Map<string, {
+  data: Doc | null
+  timestamp: number
+}>()
+
+// Cache TTL (time to live) in milliseconds
+const CACHE_TTL = isDevelopment ? 5000 : 60000 // 5s in dev, 60s in prod
+
+// Track if we've set up file watchers
+let watchersInitialized = false
+
+/**
+ * Initialize file watchers to invalidate cache on changes
+ * Only runs in development mode
+ */
+function initializeWatchers() {
+  if (!isDevelopment || watchersInitialized) return
+
+  watchersInitialized = true
+  const docsPath = join(process.cwd(), 'docs')
+
+  try {
+    watch(docsPath, { recursive: true }, (eventType, filename) => {
+      if (!filename) return
+
+      // Invalidate relevant caches when MDX or JSON files change
+      if (filename.endsWith('.mdx') || filename.endsWith('.json')) {
+        // Extract version from path
+        const parts = filename.split(/[/\\]/)
+        const version = parts[0]
+
+        // Clear all docs cache for this version
+        allDocsCache.delete(version)
+
+        // Clear individual doc caches for this version
+        const cacheKeysToDelete: string[] = []
+        docBySlugCache.forEach((_, key) => {
+          if (key.startsWith(`${version}:`)) {
+            cacheKeysToDelete.push(key)
+          }
+        })
+        cacheKeysToDelete.forEach(key => docBySlugCache.delete(key))
+
+        // Clear versions cache if directory structure changed
+        if (eventType === 'rename') {
+          versionsCache.data = null
+        }
+
+        console.log(`[MDX Cache] Invalidated cache for: ${filename}`)
+      }
+    })
+
+    console.log('[MDX Cache] File watchers initialized')
+  } catch (error) {
+    console.error('[MDX Cache] Failed to initialize watchers:', error)
+  }
+}
+
+/**
+ * Check if a cache entry is still valid
+ */
+function isCacheValid(timestamp: number): boolean {
+  return Date.now() - timestamp < CACHE_TTL
+}
+
+/**
+ * Cached version of getVersions()
+ */
+export function getCachedVersions(): string[] {
+  // Initialize watchers on first use
+  initializeWatchers()
+
+  if (versionsCache.data && isCacheValid(versionsCache.timestamp)) {
+    logCacheOperation('hit', 'versions')
+    return versionsCache.data
+  }
+
+  logCacheOperation('miss', 'versions')
+  const timer = new PerfTimer('getVersions')
+  const versions = getVersions()
+  timer.end()
+
+  versionsCache.data = versions
+  versionsCache.timestamp = Date.now()
+
+  return versions
+}
+
+/**
+ * Cached version of getAllDocs()
+ */
+export async function getCachedAllDocs(version = 'v1.0.0'): Promise<Doc[]> {
+  // Initialize watchers on first use
+  initializeWatchers()
+
+  const cached = allDocsCache.get(version)
+  if (cached && isCacheValid(cached.timestamp)) {
+    logCacheOperation('hit', `getAllDocs:${version}`)
+    return cached.data
+  }
+
+  logCacheOperation('miss', `getAllDocs:${version}`)
+  const timer = new PerfTimer(`getAllDocs(${version})`)
+  const docs = await getAllDocs(version)
+  timer.end()
+
+  allDocsCache.set(version, {
+    data: docs,
+    timestamp: Date.now(),
+  })
+
+  return docs
+}
+
+/**
+ * Cached version of getDocBySlug()
+ */
+export async function getCachedDocBySlug(
+  slug: string,
+  version = 'v1.0.0'
+): Promise<Doc | null> {
+  // Initialize watchers on first use
+  initializeWatchers()
+
+  const cacheKey = `${version}:${slug}`
+  const cached = docBySlugCache.get(cacheKey)
+
+  if (cached && isCacheValid(cached.timestamp)) {
+    logCacheOperation('hit', `getDocBySlug:${cacheKey}`)
+    return cached.data
+  }
+
+  logCacheOperation('miss', `getDocBySlug:${cacheKey}`)
+  const timer = new PerfTimer(`getDocBySlug(${slug})`)
+  const doc = await getDocBySlug(slug, version)
+  timer.end()
+
+  docBySlugCache.set(cacheKey, {
+    data: doc,
+    timestamp: Date.now(),
+  })
+
+  return doc
+}
+
+/**
+ * Manually clear all caches
+ * Useful for testing or when you want to force a refresh
+ */
+export function clearAllCaches() {
+  versionsCache.data = null
+  allDocsCache.clear()
+  docBySlugCache.clear()
+  console.log('[MDX Cache] All caches cleared')
+}
+
+/**
+ * Get cache statistics for debugging
+ */
+export function getCacheStats() {
+  return {
+    versions: {
+      cached: versionsCache.data !== null,
+      age: versionsCache.timestamp ? Date.now() - versionsCache.timestamp : 0,
+    },
+    allDocs: {
+      entries: allDocsCache.size,
+      versions: Array.from(allDocsCache.keys()),
+    },
+    docBySlug: {
+      entries: docBySlugCache.size,
+    },
+  }
+}

package/src/lib/mdx.ts

@@ -0,0 +1,402 @@
+import fs from "fs"
+import path from "path"
+import matter from "gray-matter"
+import { getAllCategoryConfigs } from "./category"
+import { sortSidebarItems, sortSidebarGroups, buildSidebarStructure, type SidebarGroup } from "./sidebar-utils"
+
+const DOCS_DIR = path.join(process.cwd(), "docs")
+
+/**
+ * Calculate reading time based on word count
+ * Average reading speed: 200 words per minute
+ */
+function calculateReadingTime(content: string): { minutes: number; words: number } {
+  const words = content.trim().split(/\s+/).length
+  const minutes = Math.ceil(words / 200)
+  return { minutes, words }
+}
+
+export interface DocMeta {
+  title: string
+  description?: string
+  slug?: string
+  section?: string
+  group?: string
+  sidebar?: string
+  order?: number
+  sidebar_position?: number
+  content?: string
+  last_updated?: string
+  draft?: boolean
+  authors?: Array<{ id: string; name?: string }>
+  tags?: string[]
+  redirect_from?: string[]
+  reading_time?: number
+  word_count?: number
+  icon?: string  // Icon name for sidebar display (Lucide icon name)
+  tab_group?: string  // Tab group ID for organizing docs into tabs
+}
+
+export interface Doc {
+  slug: string
+  filePath: string  // Original file path for sidebar grouping
+  title: string
+  meta: DocMeta
+  content: string
+  categoryLabel?: string  // Label from _category_.json
+  categoryPosition?: number  // Position from _category_.json
+  categoryCollapsible?: boolean  // Collapsible from _category_.json
+  categoryCollapsed?: boolean  // Default collapsed state from _category_.json
+  categoryIcon?: string  // Icon from _category_.json
+  categoryTabGroup?: string  // Tab group from _category_.json
+}
+
+export interface TocItem {
+  id: string
+  title: string
+  level: number
+}
+
+export function getVersions(): string[] {
+  try {
+    const versions = fs.readdirSync(DOCS_DIR)
+    return versions.filter((v) => fs.statSync(path.join(DOCS_DIR, v)).isDirectory())
+  } catch (error) {
+    return ["v1.0.0"]
+  }
+}
+
+/**
+ * Recursively find all MDX files in a directory
+ */
+function findMdxFiles(dir: string, baseDir: string = dir): string[] {
+  const files: string[] = []
+
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name)
+
+      if (entry.isDirectory()) {
+        files.push(...findMdxFiles(fullPath, baseDir))
+      } else if (entry.isFile() && entry.name.endsWith(".mdx")) {
+        // Get relative path from base directory and normalize to forward slashes
+        const relativePath = path.relative(baseDir, fullPath).replace(/\\/g, '/')
+        files.push(relativePath)
+      }
+    }
+  } catch (error) {
+    console.error(`Error reading directory ${dir}:`, error)
+  }
+
+  return files
+}
+
+/**
+ * Internal function to read a doc from file path
+ */
+function readDocFromFile(filePath: string, originalSlug: string): Doc | null {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null
+    }
+
+    const fileContents = fs.readFileSync(filePath, "utf8")
+    const { data, content } = matter(fileContents)
+
+    // Calculate reading time
+    const { minutes, words } = calculateReadingTime(content)
+
+    // If custom slug provided, replace only the filename part, keep the folder structure
+    let finalSlug = originalSlug
+    if (data.slug) {
+      const customSlug = data.slug.replace(/^\//, '')
+      const parts = originalSlug.split("/")
+
+      if (parts.length > 1) {
+        // Keep folder structure, replace only filename
+        parts[parts.length - 1] = customSlug
+        finalSlug = parts.join("/")
+      } else {
+        // Root level file, use custom slug as-is
+        finalSlug = customSlug
+      }
+    }
+
+    return {
+      slug: finalSlug,
+      filePath: originalSlug,  // Keep original file path for sidebar
+      title: data.title || originalSlug,
+      meta: {
+        ...data,
+        content,
+        reading_time: minutes,
+        word_count: words,
+      } as DocMeta,
+      content,
+    }
+  } catch (error) {
+    console.error(`Error reading file ${filePath}:`, error)
+    return null
+  }
+}
+
+export async function getDocBySlug(slug: string, version = "v1.0.0"): Promise<Doc | null> {
+  try {
+    // Try direct file first
+    let filePath = path.join(DOCS_DIR, version, `${slug}.mdx`)
+    let doc = readDocFromFile(filePath, slug)
+
+    if (doc) return doc
+
+    // If not found, try index.mdx in the folder
+    filePath = path.join(DOCS_DIR, version, slug, "index.mdx")
+    doc = readDocFromFile(filePath, slug)
+
+    if (doc) return doc
+
+    // If still not found, search all docs for a matching custom slug
+    const versionDir = path.join(DOCS_DIR, version)
+    if (!fs.existsSync(versionDir)) {
+      return null
+    }
+
+    const mdxFiles = findMdxFiles(versionDir)
+
+    for (const file of mdxFiles) {
+      const fileSlug = file.replace(/\.mdx$/, "")
+      const testPath = path.join(versionDir, file.endsWith("index.mdx") ? file : `${fileSlug}.mdx`)
+      const testDoc = readDocFromFile(testPath, fileSlug)
+
+      if (testDoc && testDoc.slug === slug) {
+        return testDoc
+      }
+    }
+
+    return null
+  } catch (error) {
+    console.error(`Error reading doc ${slug}:`, error)
+    return null
+  }
+}
+
+export async function getAllDocs(version = "v1.0.0"): Promise<Doc[]> {
+  try {
+    const versionDir = path.join(DOCS_DIR, version)
+
+    if (!fs.existsSync(versionDir)) {
+      return []
+    }
+
+    const mdxFiles = findMdxFiles(versionDir)
+    const categoryConfigs = getAllCategoryConfigs(version)
+
+    const docs = await Promise.all(
+      mdxFiles.map(async (file) => {
+        const originalFilePath = file.replace(/\.mdx$/, "")
+        let slug = originalFilePath
+
+        // If this is an index.mdx, use the directory path as the slug
+        if (file.endsWith("/index.mdx") || file === "index.mdx") {
+          slug = path.dirname(file).replace(/\\/g, '/')
+          if (slug === ".") slug = "" // Root index
+        }
+
+        const doc = await getDocBySlug(slug, version)
+
+        // Override filePath to preserve the original file structure
+        if (doc) {
+          doc.filePath = originalFilePath
+
+          // Apply category config if exists
+          const folderPath = path.dirname(originalFilePath).replace(/\\/g, '/')
+          if (folderPath !== ".") {
+            const categoryConfig = categoryConfigs.get(folderPath)
+            if (categoryConfig) {
+              doc.categoryLabel = categoryConfig.label
+              // Use position if available, otherwise fall back to sidebar_position
+              doc.categoryPosition = categoryConfig.position ?? categoryConfig.sidebar_position
+              doc.categoryCollapsible = categoryConfig.collapsible
+              doc.categoryCollapsed = categoryConfig.collapsed
+              doc.categoryIcon = categoryConfig.icon
+              doc.categoryTabGroup = categoryConfig.tab_group
+            }
+          }
+        }
+
+        return doc
+      }),
+    )
+
+    const isDevelopment = process.env.NODE_ENV === "development"
+
+    // Create a map to track unique slugs and avoid duplicates
+    const uniqueDocs = new Map<string, Doc>()
+
+    docs
+      .filter((doc): doc is Doc => doc !== null)
+      // Filter out drafts in production
+      .filter((doc) => isDevelopment || !doc.meta.draft)
+      .forEach((doc) => {
+        // Use the doc's slug (which may be custom from frontmatter) as the key
+        uniqueDocs.set(doc.slug, doc)
+      })
+
+    return Array.from(uniqueDocs.values()).sort((a, b) => {
+      const orderA = a.meta.sidebar_position ?? a.meta.order ?? 999
+      const orderB = b.meta.sidebar_position ?? b.meta.order ?? 999
+      return orderA - orderB
+    })
+  } catch (error) {
+    console.error(`Error getting all docs for version ${version}:`, error)
+    return []
+  }
+}
+
+// export function getAdjacentDocs(currentSlug: string, allDocs: Doc[]): { previous?: Doc; next?: Doc } {
+//   const currentIndex = allDocs.findIndex((doc) => doc.slug === currentSlug)
+
+//   if (currentIndex === -1) {
+//     return {}
+//   }
+
+//   return {
+//     previous: currentIndex > 0 ? allDocs[currentIndex - 1] : undefined,
+//     next: currentIndex < allDocs.length - 1 ? allDocs[currentIndex + 1] : undefined,
+//   }
+// }
+
+// Flatten the sidebar structure into a linear order
+function flattenSidebarOrder(
+  rootGroups: Record<string, SidebarGroup>,
+  standalone: Doc[]
+): Doc[] {
+  const flatDocs: Doc[] = []
+
+  // Recursively flatten groups - intermix folders and files by position
+  const flattenGroup = (group: SidebarGroup) => {
+    const sortedChildren = sortSidebarGroups(group.children)
+    const sortedItems = sortSidebarItems(group.items)
+
+    // Merge child groups and items, then sort by position
+    const merged: Array<{type: 'group', group: SidebarGroup, position: number} | {type: 'item', doc: Doc, position: number}> = [
+      ...sortedChildren.map(([, childGroup]) => ({
+        type: 'group' as const,
+        group: childGroup,
+        position: childGroup.position
+      })),
+      ...sortedItems.map((doc) => ({
+        type: 'item' as const,
+        doc,
+        position: doc.meta.sidebar_position ?? doc.meta.order ?? 999
+      }))
+    ]
+
+    // Sort by position
+    merged.sort((a, b) => a.position - b.position)
+
+    // Process in sorted order
+    merged.forEach((item) => {
+      if (item.type === 'group') {
+        flattenGroup(item.group)
+      } else {
+        flatDocs.push(item.doc)
+      }
+    })
+  }
+
+  // Add standalone items first
+  sortSidebarItems(standalone).forEach((doc) => {
+    flatDocs.push(doc)
+  })
+
+  // Then add all grouped items
+  const sortedRootGroups = sortSidebarGroups(rootGroups)
+  sortedRootGroups.forEach(([, group]) => {
+    flattenGroup(group)
+  })
+
+  return flatDocs
+}
+
+export function getAdjacentDocs(currentSlug: string, allDocs: Doc[]): { previous?: Doc; next?: Doc } {
+  // Build the same sidebar structure
+  const { rootGroups, standalone } = buildSidebarStructure(allDocs)
+
+  // Flatten into the same order as shown in the sidebar
+  const orderedDocs = flattenSidebarOrder(rootGroups, standalone)
+
+  // Find current doc in the ordered list
+  const currentIndex = orderedDocs.findIndex((doc) => doc.slug === currentSlug)
+
+  if (currentIndex === -1) {
+    return {}
+  }
+
+  const currentDoc = orderedDocs[currentIndex]
+
+  // Get current doc's tab group (from meta or category)
+  const currentTabGroup = currentDoc.meta?.tab_group || currentDoc.categoryTabGroup
+
+  // Filter docs to match the current doc's tab group status
+  // If current has a tab group, only show docs in the same tab group
+  // If current has NO tab group, only show docs with NO tab group
+  const filteredDocs = orderedDocs.filter((doc) => {
+    const docTabGroup = doc.meta?.tab_group || doc.categoryTabGroup
+
+    // If current doc has a tab group, only include docs with the same tab group
+    if (currentTabGroup) {
+      return docTabGroup === currentTabGroup
+    }
+
+    // If current doc has no tab group, only include docs with no tab group
+    return !docTabGroup
+  })
+
+  // Find current doc's index within the filtered list
+  const filteredIndex = filteredDocs.findIndex((doc) => doc.slug === currentSlug)
+
+  if (filteredIndex === -1) {
+    return {}
+  }
+
+  return {
+    previous: filteredIndex > 0 ? filteredDocs[filteredIndex - 1] : undefined,
+    next: filteredIndex < filteredDocs.length - 1 ? filteredDocs[filteredIndex + 1] : undefined,
+  }
+}
+
+export function extractTableOfContents(content: string): TocItem[] {
+  const headingRegex = /^(#{2,3})\s+(.+)$/gm
+  const toc: TocItem[] = []
+  let match
+
+  while ((match = headingRegex.exec(content)) !== null) {
+    const level = match[1].length
+    const text = match[2]
+    // Generate ID the same way rehype-slug does
+    const id = text
+      .toLowerCase()
+      .replace(/\s+/g, "-") // Replace spaces with hyphens first
+      .replace(/[^a-z0-9-]/g, "") // Remove special chars (dots, slashes, etc)
+      .replace(/^-|-$/g, "") // Remove leading/trailing hyphens
+
+    toc.push({ id, title: text, level })
+  }
+
+  return toc
+}
+
+/**
+ * Check if a slug represents a category (has child documents)
+ */
+export function isCategoryPage(slug: string, allDocs: Doc[]): boolean {
+  return allDocs.some((doc) => {
+    const parts = doc.slug.split("/")
+    const docParent = parts.slice(0, -1).join("/")
+    return docParent === slug && doc.slug !== slug
+  })
+}
+
+

package/src/lib/parsers/base-parser.ts

@@ -0,0 +1,16 @@
+import type { SpecraApiSpec } from "../api-parser.types"
+
+/**
+ * Base interface for all API spec parsers
+ */
+export interface ApiSpecParser {
+  /**
+   * Parse the input spec and convert to Specra format
+   */
+  parse(input: any): SpecraApiSpec
+
+  /**
+   * Validate if the input is in the expected format
+   */
+  validate(input: any): boolean
+}

package/src/lib/parsers/index.ts

@@ -0,0 +1,69 @@
+import type { SpecraApiSpec } from "../api-parser.types"
+import type { ApiSpecParser } from "./base-parser"
+import { SpecraParser } from "./specra-parser"
+import { OpenApiParser } from "./openapi-parser"
+import { PostmanParser } from "./postman-parser"
+
+export type ParserType = "auto" | "specra" | "openapi" | "postman"
+
+/**
+ * Registry of all available parsers
+ */
+const parsers: Map<string, ApiSpecParser> = new Map([
+  ["specra", new SpecraParser()],
+  ["openapi", new OpenApiParser()],
+  ["postman", new PostmanParser()],
+])
+
+/**
+ * Auto-detect the parser type based on the input structure
+ */
+export function detectParserType(input: any): ParserType {
+  if (!input || typeof input !== "object") {
+    throw new Error("Invalid API spec: input must be an object")
+  }
+
+  // Check for Postman Collection
+  if (input.info?.schema?.includes("v2")) {
+    return "postman"
+  }
+
+  // Check for OpenAPI/Swagger
+  if (input.openapi || input.swagger) {
+    return "openapi"
+  }
+
+  // Check for Specra format
+  if (input.endpoints && Array.isArray(input.endpoints)) {
+    return "specra"
+  }
+
+  throw new Error(
+    "Unable to auto-detect API spec format. Supported formats: Specra, OpenAPI 3.x, Postman Collection v2.x"
+  )
+}
+
+/**
+ * Parse an API spec using the specified or auto-detected parser
+ */
+export function parseApiSpec(input: any, parserType: ParserType = "auto"): SpecraApiSpec {
+  // Auto-detect if needed
+  const actualType = parserType === "auto" ? detectParserType(input) : parserType
+
+  // Get the parser
+  const parser = parsers.get(actualType)
+  if (!parser) {
+    throw new Error(`Unknown parser type: ${actualType}`)
+  }
+
+  // Validate and parse
+  if (!parser.validate(input)) {
+    throw new Error(`Input does not match ${actualType} format`)
+  }
+
+  return parser.parse(input)
+}
+
+// Export parsers for direct use
+export { SpecraParser, OpenApiParser, PostmanParser }
+export type { ApiSpecParser }