specra 0.1.13 → 0.2.0

package/dist/{mdx-ColN3Cyg.d.mts → config.types.d.ts}

@@ -4,7 +4,7 @@
 /**
  * Site metadata and branding
  */
-interface SiteConfig {
+export interface SiteConfig {
     /** The title of the documentation site */
     title: string;
     /** Short description of the documentation */
@@ -32,11 +32,13 @@ interface SiteConfig {
     hideTitle?: boolean;
     /** Whether to hide the site logo in the header */
     hideLogo?: boolean;
+    /** Project ID to tie this doc site to a Specra project for visitor tracking */
+    projectId?: string;
 }
 /**
  * Theme and appearance settings
  */
-interface ThemeConfig {
+export interface ThemeConfig {
     /** Primary color for the theme */
     primaryColor?: string;
     /** Default theme mode */
@@ -49,7 +51,7 @@ interface ThemeConfig {
 /**
  * Tab group for organizing documentation
  */
-interface TabGroup {
+export interface TabGroup {
     /** Unique identifier for the tab group */
     id: string;
     /** Display label for the tab */
@@ -60,7 +62,7 @@ interface TabGroup {
 /**
  * Navigation and sidebar configuration
  */
-interface NavigationConfig {
+export interface NavigationConfig {
     /** Whether to show the sidebar by default */
     showSidebar?: boolean;
     /** Whether the sidebar is collapsible */
@@ -75,11 +77,13 @@ interface NavigationConfig {
     tocMaxDepth?: number;
     /** Tab groups for organizing documentation sections */
     tabGroups?: TabGroup[];
+    /** Sidebar visual style: "card" (rounded container) or "flush" (attached to screen edge) */
+    sidebarStyle?: "card" | "flush";
 }
 /**
  * Social and external links
  */
-interface SocialLinks {
+export interface SocialLinks {
     /** GitHub repository URL */
     github?: string;
     /** Twitter/X handle or URL */
@@ -100,7 +104,7 @@ interface SocialLinks {
 /**
  * Search configuration
  */
-interface SearchConfig {
+export interface SearchConfig {
     /** Enable/disable search functionality */
     enabled?: boolean;
     /** Placeholder text for search input */
@@ -120,7 +124,7 @@ interface SearchConfig {
 /**
  * Analytics configuration
  */
-interface AnalyticsConfig {
+export interface AnalyticsConfig {
     /** Google Analytics tracking ID */
     googleAnalytics?: string;
     /** Google Tag Manager ID */
@@ -137,7 +141,7 @@ interface AnalyticsConfig {
 /**
  * Footer branding configuration
  */
-interface FooterBranding {
+export interface FooterBranding {
     /** Whether to show the branding */
     showBranding?: boolean;
     /** Logo for the branding - can be a string or an object with light/dark variants */
@@ -153,7 +157,7 @@ interface FooterBranding {
 /**
  * Footer configuration
  */
-interface FooterConfig {
+export interface FooterConfig {
     /** Copyright text */
     copyright?: string;
     /** Footer links organized by columns */
@@ -172,7 +176,7 @@ interface FooterConfig {
 /**
  * Documentation features
  */
-interface FeaturesConfig {
+export interface FeaturesConfig {
     /**
      * Enable/disable edit this page links.
      * Provide a URL template (e.g., "https://github.com/user/repo/edit/main/docs") or false to disable
@@ -188,6 +192,8 @@ interface FeaturesConfig {
     showTags?: boolean;
     /** Enable version dropdown */
     versioning?: boolean;
+    /** Show version badge in the sidebar */
+    showVersionBadge?: boolean;
     /**
      * Internationalization (i18n) configuration
      * Set to true to enable with defaults, or provide configuration object
@@ -197,7 +203,7 @@ interface FeaturesConfig {
 /**
  * Internationalization configuration
  */
-interface I18nConfig {
+export interface I18nConfig {
     /** The default locale (e.g. 'en') - used when no locale is present in URL */
     defaultLocale: string;
     /** List of supported locales (e.g. ['en', 'fr', 'es']) */
@@ -210,7 +216,7 @@ interface I18nConfig {
 /**
  * Site-wide banner configuration
  */
-interface BannerConfig {
+export interface BannerConfig {
     /** Whether the banner is enabled */
     enabled?: boolean;
     /** Banner message */
@@ -224,7 +230,7 @@ interface BannerConfig {
  * Environment variables that can be used in documentation
  * These will be replaced at build time or runtime
  */
-interface EnvironmentVariables {
+export interface EnvironmentVariables {
     /** API base URL */
     API_BASE_URL?: string;
     /** API version */
@@ -237,7 +243,7 @@ interface EnvironmentVariables {
 /**
  * Deployment configuration for different hosting scenarios
  */
-interface DeploymentConfig {
+export interface DeploymentConfig {
     /**
      * Deployment target
      * - 'vercel': For Vercel or similar Node.js hosting (uses 'standalone' output)
@@ -261,7 +267,7 @@ interface DeploymentConfig {
 /**
  * Main configuration interface
  */
-interface SpecraConfig {
+export interface SpecraConfig {
     /** JSON Schema reference (for IDE support) */
     $schema?: string;
     /** Site metadata and branding */
@@ -290,63 +296,4 @@ interface SpecraConfig {
 /**
  * Default configuration values
  */
-declare const defaultConfig: SpecraConfig;
-
-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;
-    tab_group?: string;
-    locale?: string;
-}
-interface Doc {
-    slug: string;
-    filePath: string;
-    title: string;
-    meta: DocMeta;
-    content: string;
-    categoryLabel?: string;
-    categoryPosition?: number;
-    categoryCollapsible?: boolean;
-    categoryCollapsed?: boolean;
-    categoryIcon?: string;
-    categoryTabGroup?: string;
-    locale?: string;
-}
-interface TocItem {
-    id: string;
-    title: string;
-    level: number;
-}
-declare function getVersions(): string[];
-declare function getI18nConfig(): I18nConfig | null;
-declare function getDocBySlug(slug: string, version?: string, locale?: string): Promise<Doc | null>;
-declare function getAllDocs(version?: string, locale?: string): Promise<Doc[]>;
-declare function getAdjacentDocs(currentSlug: string, allDocs: Doc[]): {
-    previous?: Doc;
-    next?: Doc;
-};
-declare function extractTableOfContents(content: string): TocItem[];
-/**
- * Check if a slug represents a category (has child documents)
- */
-declare function isCategoryPage(slug: string, allDocs: Doc[]): boolean;
-
-export { type AnalyticsConfig as A, type BannerConfig as B, type DocMeta as D, type EnvironmentVariables as E, type FooterBranding as F, type I18nConfig as I, type NavigationConfig as N, type SpecraConfig as S, type TocItem as T, type Doc as a, getI18nConfig as b, getDocBySlug as c, getAllDocs as d, getAdjacentDocs as e, extractTableOfContents as f, getVersions as g, defaultConfig as h, isCategoryPage as i, type SiteConfig as j, type ThemeConfig as k, type TabGroup as l, type SocialLinks as m, type SearchConfig as n, type FooterConfig as o, type FeaturesConfig as p, type DeploymentConfig as q };
+export declare const defaultConfig: SpecraConfig;

package/dist/config.types.js

@@ -0,0 +1,39 @@
+/**
+ * Configuration schema for Specra documentation system
+ */
+/**
+ * Default configuration values
+ */
+export const defaultConfig = {
+    site: {
+        title: "Documentation",
+        description: "Project documentation",
+        baseUrl: "/",
+        language: "en",
+    },
+    theme: {
+        defaultMode: "system",
+        respectPrefersColorScheme: true,
+    },
+    navigation: {
+        showSidebar: true,
+        collapsibleSidebar: true,
+        showBreadcrumbs: true,
+        showTableOfContents: true,
+        tocPosition: "right",
+        tocMaxDepth: 3,
+    },
+    search: {
+        enabled: true,
+        provider: "local",
+        placeholder: "Search documentation...",
+    },
+    features: {
+        showLastUpdated: true,
+        showReadingTime: true,
+        showAuthors: false,
+        showTags: true,
+        versioning: true,
+        i18n: false,
+    },
+};

package/dist/dev-utils.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Development utilities for debugging and performance monitoring
+ * Only active in development mode
+ */
+/**
+ * Performance timer for measuring operation duration
+ */
+export declare class PerfTimer {
+    private startTime;
+    private label;
+    constructor(label: string);
+    end(): void;
+}
+/**
+ * Log file system operations
+ */
+export declare function logFsOperation(operation: string, path: string, details?: any): void;
+/**
+ * Log cache operations
+ */
+export declare function logCacheOperation(operation: 'hit' | 'miss' | 'invalidate', key: string): void;
+/**
+ * Memory usage reporter
+ */
+export declare function logMemoryUsage(label?: string): void;
+/**
+ * Pretty print object for debugging
+ */
+export declare function debugLog(label: string, data: any): void;

package/dist/dev-utils.js

@@ -0,0 +1,63 @@
+/**
+ * Development utilities for debugging and performance monitoring
+ * Only active in development mode
+ */
+const isDevelopment = process.env.NODE_ENV === 'development';
+/**
+ * Performance timer for measuring operation duration
+ */
+export class PerfTimer {
+    constructor(label) {
+        this.label = label;
+        this.startTime = isDevelopment ? performance.now() : 0;
+    }
+    end() {
+        if (!isDevelopment)
+            return;
+        const duration = performance.now() - this.startTime;
+        const color = duration > 1000 ? '\x1b[31m' : duration > 500 ? '\x1b[33m' : '\x1b[32m';
+        const reset = '\x1b[0m';
+        console.log(`${color}⏱️  ${this.label}: ${duration.toFixed(2)}ms${reset}`);
+    }
+}
+/**
+ * Log file system operations
+ */
+export function logFsOperation(operation, path, details) {
+    if (!isDevelopment)
+        return;
+    console.log(`📁 [FS] ${operation}: ${path}`, details || '');
+}
+/**
+ * Log cache operations
+ */
+export function logCacheOperation(operation, key) {
+    if (!isDevelopment)
+        return;
+    const emoji = operation === 'hit' ? '✅' : operation === 'miss' ? '❌' : '🔄';
+    console.log(`${emoji} [Cache] ${operation}: ${key}`);
+}
+/**
+ * Memory usage reporter
+ */
+export function logMemoryUsage(label) {
+    if (!isDevelopment)
+        return;
+    const used = process.memoryUsage();
+    const prefix = label ? `[${label}] ` : '';
+    console.log(`💾 ${prefix}Memory Usage:`, {
+        rss: `${Math.round(used.rss / 1024 / 1024)}MB`,
+        heapTotal: `${Math.round(used.heapTotal / 1024 / 1024)}MB`,
+        heapUsed: `${Math.round(used.heapUsed / 1024 / 1024)}MB`,
+    });
+}
+/**
+ * Pretty print object for debugging
+ */
+export function debugLog(label, data) {
+    if (!isDevelopment)
+        return;
+    console.log(`\n🔍 ${label}:`);
+    console.dir(data, { depth: null, colors: true });
+    console.log('');
+}

package/dist/index.d.ts

@@ -1,4 +1,19 @@
-export { A as AnalyticsConfig, B as BannerConfig, q as DeploymentConfig, a as Doc, D as DocMeta, E as EnvironmentVariables, p as FeaturesConfig, F as FooterBranding, o as FooterConfig, I as I18nConfig, N as NavigationConfig, n as SearchConfig, j as SiteConfig, m as SocialLinks, S as SpecraConfig, l as TabGroup, k as ThemeConfig, T as TocItem, h as defaultConfig, f as extractTableOfContents, e as getAdjacentDocs, d as getAllDocs, c as getDocBySlug, b as getI18nConfig, g as getVersions, i as isCategoryPage } from './mdx-ColN3Cyg.js';
-export { ApiAuthentication, ApiDocumentation, ApiEndpointSpec, ApiExample, ApiHeader, ApiParam, ApiParameter, ApiResponse, ApiSpecConfig, ApiSpecParser, CSP_DIRECTIVES, CategoryConfig, GraphQLField, GraphQLQuery, GraphQLSchema, GraphQLType, HttpMethod, OpenApiParser, ParsedApiSpec, ParserType, PerfTimer, PostmanParser, RedirectMapping, RestEndpoint, SAFE_MDX_COMPONENTS, SidebarGroup, SpecraApiResponse, SpecraApiSpec, SpecraParser, TOCItem, WebSocketConnection, WebSocketEvent, buildRedirectMappings, buildSidebarStructure, clearAllCaches, cn, debugLog, detectParserType, extractHeadings, findRedirect, generateCSPHeader, getAllCategoryConfigs, getAssetPath, getCacheStats, getCachedAllDocs, getCachedDocBySlug, getCachedVersions, getCategoryConfig, getConfig, getConfigValue, initConfig, loadConfig, logCacheOperation, logFsOperation, logMemoryUsage, parseApiSpec, processContentWithEnv, reloadConfig, replaceEnvVariables, sanitizeMDXContent, sanitizePath, scanMDXForDangerousPatterns, sortSidebarGroups, sortSidebarItems, validateConfig, validateMDXComponents, validateMDXSecurity, validatePathWithinDirectory } from './lib/index.js';
-export * from './components/index.ts';
-import 'clsx';
+export * from './components/index.js';
+export * from './stores/index.js';
+export * from './mdx-components.js';
+export * from './mdx.js';
+export * from './mdx-cache.js';
+export * from './toc.js';
+export * from './config.server.js';
+export * from './config.js';
+export type * from './config.types.js';
+export * from './parsers/index.js';
+export type * from './api.types.js';
+export type { ApiParam, ApiHeader, ApiResponse as SpecraApiResponse, ApiEndpointSpec, SpecraApiSpec } from './api-parser.types.js';
+export * from './utils.js';
+export * from './sidebar-utils.js';
+export * from './category.js';
+export * from './redirects.js';
+export * from './dev-utils.js';
+export * from './mdx-security.js';
+export * from './middleware/index.js';