specra 0.1.13 → 0.2.0

package/dist/lib/index.d.ts

@@ -1,583 +0,0 @@
-import { a as Doc, S as SpecraConfig } from '../mdx-ColN3Cyg.js';
-export { A as AnalyticsConfig, B as BannerConfig, q as DeploymentConfig, 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, 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';
-import { ClassValue } from 'clsx';
-import '../components/index.ts';
-
-/**
- * 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.
- */
-
-/**
- * Cached version of getVersions()
- */
-declare function getCachedVersions(): string[];
-/**
- * Cached version of getAllDocs()
- */
-declare function getCachedAllDocs(version?: string, locale?: string): Promise<Doc[]>;
-/**
- * Cached version of getDocBySlug()
- */
-declare function getCachedDocBySlug(slug: string, version?: string): Promise<Doc | null>;
-/**
- * Manually clear all caches
- * Useful for testing or when you want to force a refresh
- */
-declare function clearAllCaches(): void;
-/**
- * Get cache statistics for debugging
- */
-declare function getCacheStats(): {
-    versions: {
-        cached: boolean;
-        age: number;
-    };
-    allDocs: {
-        entries: number;
-        versions: string[];
-    };
-    docBySlug: {
-        entries: number;
-    };
-};
-
-interface TOCItem {
-    id: string;
-    title: string;
-    level: number;
-}
-/**
- * Extract headings from HTML string for table of contents
- */
-declare function extractHeadings(html: string): TOCItem[];
-
-/**
- * Load and parse the Specra configuration file
- * Falls back to default configuration if file doesn't exist or is invalid
- */
-declare function loadConfig(userConfig: Partial<SpecraConfig>): SpecraConfig;
-/**
- * Get a specific configuration value by path (SERVER ONLY)
- * Example: getConfigValue('site.title') or getConfigValue('theme.defaultMode')
- */
-declare function getConfigValue<T = any>(path: string, config?: SpecraConfig): T | undefined;
-/**
- * Replace environment variables in a string (SERVER ONLY)
- * Supports ${ENV_VAR} and {{ENV_VAR}} syntax
- */
-declare function replaceEnvVariables(text: string, config?: SpecraConfig): string;
-/**
- * Process content and replace all environment variables (SERVER ONLY)
- */
-declare function processContentWithEnv(content: string, config?: SpecraConfig): string;
-/**
- * Validate configuration (basic validation) (SERVER ONLY)
- */
-declare function validateConfig(config: SpecraConfig): {
-    valid: boolean;
-    errors: string[];
-};
-/**
- * Initialize the Specra configuration
- * Can be called multiple times - subsequent calls will update the config
- * @param userConfig - Partial configuration to merge with defaults
- * @returns The initialized configuration
- */
-declare function initConfig(userConfig: Partial<SpecraConfig>): SpecraConfig;
-/**
- * Get the configuration instance (cached) (SERVER ONLY)
- * If not initialized, returns default config
- */
-declare function getConfig(): SpecraConfig;
-/**
- * Reload the configuration (useful for development) (SERVER ONLY)
- */
-declare function reloadConfig(userConfig: Partial<SpecraConfig>): SpecraConfig;
-
-/**
- * Simple API Documentation Format for Specra
- * Easy to write, easy to parse
- */
-interface ApiParam {
-    name: string;
-    type: string;
-    required?: boolean;
-    description?: string;
-    default?: any;
-    example?: any;
-}
-interface ApiHeader {
-    name: string;
-    value: string;
-    description?: string;
-}
-interface ApiResponse$1 {
-    status: number;
-    description?: string;
-    example?: any;
-    schema?: any;
-}
-interface ApiEndpointSpec {
-    title: string;
-    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
-    path: string;
-    description?: string;
-    pathParams?: ApiParam[];
-    queryParams?: ApiParam[];
-    headers?: ApiHeader[];
-    body?: {
-        description?: string;
-        example?: any;
-        schema?: any;
-    };
-    successResponse?: ApiResponse$1;
-    errorResponses?: ApiResponse$1[];
-    examples?: {
-        title: string;
-        language: string;
-        code: string;
-    }[];
-}
-interface SpecraApiSpec {
-    version?: string;
-    title?: string;
-    description?: string;
-    baseUrl: string;
-    env?: Record<string, string>;
-    globalHeaders?: ApiHeader[];
-    auth?: {
-        type: "bearer" | "apiKey" | "basic";
-        description?: string;
-        headerName?: string;
-        tokenPrefix?: string;
-    };
-    endpoints: ApiEndpointSpec[];
-}
-
-/**
- * Base interface for all API spec parsers
- */
-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;
-}
-
-/**
- * Parser for native Specra API format
- * This is a pass-through parser since the input is already in the correct format
- */
-declare class SpecraParser implements ApiSpecParser {
-    validate(input: any): boolean;
-    parse(input: any): SpecraApiSpec;
-}
-
-/**
- * Parser for OpenAPI 3.0/3.1 specifications
- */
-declare class OpenApiParser implements ApiSpecParser {
-    validate(input: any): boolean;
-    parse(input: any): SpecraApiSpec;
-    private extractBaseUrl;
-    private extractAuth;
-    private parseOperation;
-    private convertPathParams;
-    private parseParameters;
-    private parseRequestBody;
-    private parseResponses;
-    private generateExample;
-    private resolveRef;
-}
-
-/**
- * Parser for Postman Collection v2.0/v2.1
- */
-declare class PostmanParser implements ApiSpecParser {
-    validate(input: any): boolean;
-    parse(input: any): SpecraApiSpec;
-    private extractBaseUrl;
-    private findFirstRequest;
-    private extractAuth;
-    private extractGlobalHeaders;
-    private parseItems;
-    private parseRequest;
-    private parseUrl;
-    private buildPath;
-    private parseUrlParams;
-    private parseBody;
-    private parseResponses;
-}
-
-type ParserType = "auto" | "specra" | "openapi" | "postman";
-/**
- * Auto-detect the parser type based on the input structure
- */
-declare function detectParserType(input: any): ParserType;
-/**
- * Parse an API spec using the specified or auto-detected parser
- */
-declare function parseApiSpec(input: any, parserType?: ParserType): SpecraApiSpec;
-
-/**
- * Specra API Documentation Schema
- * Supports REST, GraphQL, and WebSocket APIs
- */
-type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
-interface ApiParameter {
-    name: string;
-    type: string;
-    required?: boolean;
-    description?: string;
-    default?: any;
-    example?: any;
-    enum?: string[];
-}
-interface ApiResponse {
-    status: number;
-    description: string;
-    schema?: any;
-    example?: any;
-    headers?: Record<string, string>;
-}
-interface ApiExample {
-    title: string;
-    language: string;
-    code: string;
-}
-interface ApiAuthentication {
-    type: "apiKey" | "bearer" | "basic" | "oauth2" | "none";
-    description?: string;
-    location?: "header" | "query" | "cookie";
-    name?: string;
-    scheme?: string;
-}
-interface RestEndpoint {
-    type: "rest";
-    method: HttpMethod;
-    path: string;
-    summary: string;
-    description?: string;
-    operationId?: string;
-    tags?: string[];
-    deprecated?: boolean;
-    authentication?: ApiAuthentication;
-    pathParams?: ApiParameter[];
-    queryParams?: ApiParameter[];
-    headers?: ApiParameter[];
-    body?: {
-        contentType: string;
-        schema?: any;
-        example?: any;
-        description?: string;
-    };
-    responses: ApiResponse[];
-    examples?: ApiExample[];
-}
-interface GraphQLField {
-    name: string;
-    type: string;
-    description?: string;
-    args?: ApiParameter[];
-    deprecated?: boolean;
-    deprecationReason?: string;
-}
-interface GraphQLType {
-    name: string;
-    kind: "OBJECT" | "INPUT_OBJECT" | "ENUM" | "SCALAR" | "INTERFACE" | "UNION";
-    description?: string;
-    fields?: GraphQLField[];
-    enumValues?: {
-        name: string;
-        description?: string;
-    }[];
-}
-interface GraphQLQuery {
-    type: "graphql";
-    operationType: "query" | "mutation" | "subscription";
-    name: string;
-    description?: string;
-    args?: ApiParameter[];
-    returnType: string;
-    example?: string;
-    response?: any;
-}
-interface GraphQLSchema {
-    queries?: GraphQLQuery[];
-    mutations?: GraphQLQuery[];
-    subscriptions?: GraphQLQuery[];
-    types?: GraphQLType[];
-}
-interface WebSocketEvent {
-    type: "websocket";
-    event: string;
-    direction: "client-to-server" | "server-to-client" | "bidirectional";
-    description?: string;
-    payload?: {
-        schema?: any;
-        example?: any;
-    };
-    response?: {
-        schema?: any;
-        example?: any;
-    };
-}
-interface WebSocketConnection {
-    url: string;
-    authentication?: ApiAuthentication;
-    description?: string;
-    events: WebSocketEvent[];
-}
-interface ApiDocumentation {
-    version: string;
-    title: string;
-    description?: string;
-    baseUrl?: string;
-    servers?: Array<{
-        url: string;
-        description?: string;
-    }>;
-    rest?: {
-        endpoints: RestEndpoint[];
-    };
-    graphql?: GraphQLSchema;
-    websocket?: WebSocketConnection[];
-    authentication?: ApiAuthentication[];
-    headers?: Record<string, string>;
-}
-interface ApiSpecConfig {
-    source: "openapi" | "postman" | "insomnia" | "specra" | "manual";
-    path?: string;
-    spec?: ApiDocumentation;
-    autoGenerate?: boolean;
-    outputDir?: string;
-}
-interface ParsedApiSpec {
-    source: ApiSpecConfig["source"];
-    documentation: ApiDocumentation;
-}
-
-declare function cn(...inputs: ClassValue[]): string;
-/**
- * Get the correct asset path based on deployment configuration
- * Handles different deployment scenarios:
- * - Vercel/Node.js hosting (standalone build): No basePath needed
- * - GitHub Pages without custom domain: Uses basePath from config
- * - Static hosting with custom domain: No basePath needed
- *
- * @param path - The asset path (can start with or without '/')
- * @returns The properly formatted asset path
- */
-declare function getAssetPath(path: string): string;
-
-/**
- * Unified sidebar sorting and structure building utilities
- * This module provides consistent sidebar logic across the application
- * to ensure ordering is handled the same way everywhere.
- */
-interface SidebarGroup {
-    label: string;
-    path: string;
-    icon?: string;
-    items: any[];
-    position: number;
-    collapsible: boolean;
-    defaultCollapsed: boolean;
-    children: Record<string, SidebarGroup>;
-}
-/**
- * Sort sidebar items by their position.
- * Items with explicit sidebar_position come first (sorted numerically),
- * followed by items without position (sorted by their original order).
- *
- * @param items - Array of items with optional sidebar_position
- * @returns Sorted array of items
- */
-declare function sortSidebarItems<T extends {
-    sidebar_position?: number;
-    meta?: any;
-}>(items: T[]): T[];
-/**
- * Sort sidebar groups by their position.
- * Groups with explicit position come first (sorted numerically),
- * followed by groups without position at the end (sorted by their original order).
- *
- * @param groups - Record of group key to group object with position
- * @returns Sorted array of [key, group] tuples
- */
-declare function sortSidebarGroups<T extends {
-    position: number;
-}>(groups: Record<string, T>): [string, T][];
-/**
- * Build hierarchical sidebar structure from flat list of documents
- * This is the single source of truth for sidebar structure used by both
- * the sidebar component and navigation (prev/next) links.
- *
- * @param docs - Array of documents with metadata
- * @returns Object containing root groups and standalone items
- */
-declare function buildSidebarStructure<T extends {
-    filePath: string;
-    slug: string;
-    categoryLabel?: string;
-    categoryPosition?: number;
-    categoryIcon?: string;
-    categoryCollapsible?: boolean;
-    categoryCollapsed?: boolean;
-    meta: any;
-}>(docs: T[]): {
-    rootGroups: Record<string, SidebarGroup>;
-    standalone: T[];
-};
-
-interface CategoryConfig {
-    label?: string;
-    position?: number;
-    sidebar_position?: number;
-    link?: {
-        type: "generated-index" | "doc";
-        slug?: string;
-    };
-    collapsed?: boolean;
-    collapsible?: boolean;
-    icon?: string;
-    tab_group?: string;
-}
-/**
- * Read category.json from a folder
- */
-declare function getCategoryConfig(folderPath: string): CategoryConfig | null;
-/**
- * Get all category configs for a version
- */
-declare function getAllCategoryConfigs(version: string): Map<string, CategoryConfig>;
-
-interface RedirectMapping {
-    from: string;
-    to: string;
-}
-/**
- * Build redirect mappings from all docs' redirect_from frontmatter
- */
-declare function buildRedirectMappings(): Promise<RedirectMapping[]>;
-/**
- * Find redirect destination for a given path
- */
-declare function findRedirect(path: string): Promise<string | null>;
-
-/**
- * Development utilities for debugging and performance monitoring
- * Only active in development mode
- */
-/**
- * Performance timer for measuring operation duration
- */
-declare class PerfTimer {
-    private startTime;
-    private label;
-    constructor(label: string);
-    end(): void;
-}
-/**
- * Log file system operations
- */
-declare function logFsOperation(operation: string, path: string, details?: any): void;
-/**
- * Log cache operations
- */
-declare function logCacheOperation(operation: 'hit' | 'miss' | 'invalidate', key: string): void;
-/**
- * Memory usage reporter
- */
-declare function logMemoryUsage(label?: string): void;
-/**
- * Pretty print object for debugging
- */
-declare function debugLog(label: string, data: any): void;
-
-/**
- * MDX Security Layer
- *
- * Protects against:
- * - XSS via malicious MDX expressions
- * - Path traversal attacks
- * - Dangerous component usage
- * - Cross-domain vulnerabilities
- */
-/**
- * Sanitize file paths to prevent path traversal attacks
- * Blocks: ../, ..\, absolute paths, encoded traversal attempts
- */
-declare function sanitizePath(userPath: string): string;
-/**
- * Validate that a file path is within allowed directory
- */
-declare function validatePathWithinDirectory(filePath: string, allowedDir: string): boolean;
-/**
- * Scan MDX content for dangerous patterns
- * Returns array of detected issues
- * Note: Skips content inside code blocks to avoid false positives
- */
-declare function scanMDXForDangerousPatterns(content: string): string[];
-/**
- * Sanitize MDX content by removing/escaping dangerous patterns
- * This is a defensive measure - ideally content should be rejected if dangerous
- */
-declare function sanitizeMDXContent(content: string, strict?: boolean): string;
-/**
- * Content Security Policy configuration
- * Use this in your Next.js middleware or headers config
- */
-declare const CSP_DIRECTIVES: {
-    readonly "default-src": readonly ["'self'"];
-    readonly "script-src": readonly ["'self'", "'unsafe-inline'", "'unsafe-eval'"];
-    readonly "style-src": readonly ["'self'", "'unsafe-inline'"];
-    readonly "img-src": readonly ["'self'", "data:", "https:"];
-    readonly "font-src": readonly ["'self'", "data:"];
-    readonly "connect-src": readonly ["'self'"];
-    readonly "frame-src": readonly ["'self'"];
-    readonly "object-src": readonly ["'none'"];
-    readonly "base-uri": readonly ["'self'"];
-    readonly "form-action": readonly ["'self'"];
-    readonly "frame-ancestors": readonly ["'self'"];
-    readonly "upgrade-insecure-requests": readonly [];
-};
-/**
- * Generate CSP header value from directives
- */
-declare function generateCSPHeader(customDirectives?: Partial<typeof CSP_DIRECTIVES>, production?: boolean): string;
-/**
- * Allowlist of safe MDX components
- * Only these components can be used in MDX files
- */
-declare const SAFE_MDX_COMPONENTS: Set<string>;
-/**
- * Validate component usage in MDX
- */
-declare function validateMDXComponents(content: string): {
-    valid: boolean;
-    issues: string[];
-};
-/**
- * Comprehensive MDX security check
- * Use this before processing MDX content
- */
-declare function validateMDXSecurity(content: string, options?: {
-    strictMode?: boolean;
-    allowCustomComponents?: boolean;
-    blockDangerousPatterns?: boolean;
-}): {
-    valid: boolean;
-    issues: string[];
-    sanitized?: string;
-};
-
-export { type ApiAuthentication, type ApiDocumentation, type ApiEndpointSpec, type ApiExample, type ApiHeader, type ApiParam, type ApiParameter, type ApiResponse, type ApiSpecConfig, type ApiSpecParser, CSP_DIRECTIVES, type CategoryConfig, Doc, type GraphQLField, type GraphQLQuery, type GraphQLSchema, type GraphQLType, type HttpMethod, OpenApiParser, type ParsedApiSpec, type ParserType, PerfTimer, PostmanParser, type RedirectMapping, type RestEndpoint, SAFE_MDX_COMPONENTS, type SidebarGroup, type ApiResponse$1 as SpecraApiResponse, type SpecraApiSpec, SpecraConfig, SpecraParser, type TOCItem, type WebSocketConnection, type 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 };