Core Highlighting

/**
 * Highlights code with specified language
 * @param code - The code string to highlight
 * @param options - Highlighting options
 * @returns Result object with highlighted HTML and metadata
 */
function highlight(code: string, options: HighlightOptions): HighlightResult;

interface HighlightOptions {
  /** Language identifier (e.g., 'javascript', 'python', 'html') */
  language: string;
  /** Whether to ignore illegal language constructs */
  ignoreIllegals?: boolean;
}

import hljs from 'highlight.js';

// Highlight JavaScript code
const result = hljs.highlight('const x = 42;', { language: 'javascript' });
console.log(result.value); // HTML with syntax highlighting
console.log(result.language); // 'javascript'
console.log(result.relevance); // Confidence score

// Highlight with error tolerance
const htmlResult = hljs.highlight('<div>content</div>', { 
  language: 'html',
  ignoreIllegals: true 
});

// Handle potential highlighting errors
if (result.errorRaised) {
  console.error('Highlighting failed:', result.errorRaised);
}

/**
 * @deprecated Use highlight(code, {language: languageName, ignoreIllegals}) instead
 * Legacy highlighting function for backwards compatibility
 * @param languageName - Language identifier
 * @param code - Code to highlight
 * @param ignoreIllegals - Whether to ignore illegal constructs
 * @returns Highlight result
 */
function highlight(languageName: string, code: string, ignoreIllegals?: boolean): HighlightResult;

// Legacy API (deprecated but still functional)
const result = hljs.highlight('javascript', 'const x = 42;', true);

/**
 * Automatically detects language and highlights code
 * @param code - Code string to highlight
 * @param languageSubset - Optional array of languages to consider
 * @returns Auto-detection result with best and alternative matches
 */
function highlightAuto(code: string, languageSubset?: string[]): AutoHighlightResult;

interface AutoHighlightResult extends HighlightResult {
  /** Alternative language detection result */
  secondBest?: Omit<HighlightResult, 'secondBest'>;
}

// Auto-detect any language
const result = hljs.highlightAuto('console.log("Hello World");');
console.log(result.language); // 'javascript' (detected)
console.log(result.relevance); // Confidence score
console.log(result.value); // Highlighted HTML

// Limit detection to specific languages
const webResult = hljs.highlightAuto('<div class="container"></div>', ['html', 'xml', 'css']);
console.log(webResult.language); // 'html' (detected from subset)

// Check for alternative detection
if (result.secondBest) {
  console.log('Alternative:', result.secondBest.language, result.secondBest.relevance);
}

// Handle edge cases with very short code
const shortResult = hljs.highlightAuto('x');
if (shortResult.relevance < 5) {
  console.log('Low confidence detection, consider manual language specification');
}

/**
 * Check if a language has auto-detection enabled
 * @param languageName - Name of the language to check
 * @returns Whether auto-detection is available for this language
 */
function autoDetection(languageName: string): boolean;

// Check detection capability
if (hljs.autoDetection('javascript')) {
  console.log('JavaScript supports auto-detection');
}

// Check multiple languages
const languages = ['python', 'brainfuck', 'assembly'];
const detectable = languages.filter(lang => hljs.autoDetection(lang));
console.log('Auto-detectable languages:', detectable);

interface HighlightResult {
  /** Highlighted HTML output */
  value: string;
  /** Detected or specified language */
  language?: string;
  /** Confidence score (0-10+, higher is better) */
  relevance: number;
  /** Whether illegal language constructs were encountered */
  illegal: boolean;
  /** Error that occurred during highlighting, if any */
  errorRaised?: Error;
  /** Second-best language match (auto-detection only) */
  secondBest?: Omit<HighlightResult, 'secondBest'>;
  /** Raw code input (not highlighted) */
  code?: string;
}

// Handle unknown languages
const result = hljs.highlight('some code', { language: 'nonexistent' });
if (!result.language) {
  console.log('Language not found, no highlighting applied');
}

// Graceful degradation for malformed code
const malformedResult = hljs.highlight('unclosed "string', { 
  language: 'javascript',
  ignoreIllegals: true 
});
console.log('Partial highlighting applied despite syntax errors');

// Auto-detection fallback
const autoResult = hljs.highlightAuto('some ambiguous code');
if (autoResult.relevance < 3) {
  console.log('Low confidence, consider fallback to plain text');
}