/** * HTML renderer for dependency graph visualization. * * This module generates self-contained HTML files with embedded D3.js * visualization of workspace dependencies. The output is a single HTML * file that works offline without any external network requests. * * Security: All embedded data is sanitized to prevent XSS attacks. */ import type {Result} from '../types/index' import type {VisualizationData} from './types' import {err, ok} from '@bfra.me/es/result' import {generateControlPanelScript, generateGraphInitScript} from './templates/graph-template' import {generateStyles, SEVERITY_COLORS} from './templates/styles' /** * Error types for HTML rendering failures. */ export interface HtmlRenderError { /** Error code for programmatic handling */ readonly code: 'RENDER_FAILED' | 'INVALID_DATA' | 'SANITIZATION_FAILED' /** Human-readable error message */ readonly message: string /** Optional details about the error */ readonly details?: Record } /** * Options for HTML rendering. */ export interface HtmlRenderOptions { /** Title for the HTML document */ readonly title: string /** Whether to include the D3.js library inline */ readonly inlineD3: boolean /** Whether to minify the output */ readonly minify: boolean /** Custom CSS to append */ readonly customCss?: string /** Custom JavaScript to append */ readonly customJs?: string } /** * Default HTML render options. */ export const DEFAULT_HTML_RENDER_OPTIONS: HtmlRenderOptions = { title: 'Workspace Dependency Graph', inlineD3: true, minify: false, } /** * Sanitizes a string for safe embedding in HTML. * Prevents XSS by escaping dangerous characters. * * @param str - The string to sanitize * @returns Sanitized string safe for HTML embedding */ export function sanitizeHtml(str: string): string { if (typeof str !== 'string') { return '' } return str .replaceAll('&', '&') .replaceAll('<', '<') .replaceAll('>', '>') .replaceAll('"', '"') .replaceAll("'", ''') .replaceAll('/', '/') .replaceAll('`', '`') .replaceAll('=', '=') } /** * Sanitizes a string for safe embedding in JavaScript string literals. * Escapes characters that could break out of string context. * * @param str - The string to sanitize * @returns Sanitized string safe for JavaScript embedding */ export function sanitizeJsString(str: string): string { if (typeof str !== 'string') { return '' } return str .replaceAll('\\', '\\\\') .replaceAll("'", String.raw`\'`) .replaceAll('"', String.raw`\"`) .replaceAll('\n', String.raw`\n`) .replaceAll('\r', String.raw`\r`) .replaceAll('\t', String.raw`\t`) .replaceAll('\u2028', String.raw`\u2028`) .replaceAll('\u2029', String.raw`\u2029`) .replaceAll('', String.raw`<\/script>`) } /** * Sanitizes a file path for safe embedding. * Removes potentially dangerous path traversal attempts. * * @param path - The file path to sanitize * @returns Sanitized file path */ export function sanitizeFilePath(path: string): string { if (typeof path !== 'string') { return '' } // Remove null bytes and normalize path separators return path.replaceAll('\0', '').replaceAll('../', '').replaceAll(/\.\.$/g, '') } /** * Sanitizes visualization data for safe embedding in HTML/JavaScript. * * @param data - The visualization data to sanitize * @returns Sanitized visualization data */ export function sanitizeVisualizationData(data: VisualizationData): VisualizationData { return { nodes: data.nodes.map(node => ({ ...node, id: sanitizeJsString(node.id), name: sanitizeJsString(node.name), filePath: sanitizeJsString(sanitizeFilePath(node.filePath)), packageName: node.packageName === undefined ? undefined : sanitizeJsString(node.packageName), layer: node.layer === undefined ? undefined : sanitizeJsString(node.layer), violations: node.violations.map(v => ({ ...v, id: sanitizeJsString(v.id), message: sanitizeJsString(v.message), ruleId: sanitizeJsString(v.ruleId), })), })), edges: data.edges.map(edge => ({ ...edge, source: sanitizeJsString(edge.source), target: sanitizeJsString(edge.target), cycleId: edge.cycleId === undefined ? undefined : sanitizeJsString(edge.cycleId), })), cycles: data.cycles.map(cycle => ({ ...cycle, id: sanitizeJsString(cycle.id), nodes: cycle.nodes.map(n => sanitizeJsString(n)), edges: cycle.edges.map(e => ({ from: sanitizeJsString(e.from), to: sanitizeJsString(e.to), })), description: sanitizeJsString(cycle.description), })), statistics: data.statistics, layers: data.layers.map(layer => ({ ...layer, name: sanitizeJsString(layer.name), allowedDependencies: layer.allowedDependencies.map(d => sanitizeJsString(d)), })), metadata: { ...data.metadata, workspacePath: sanitizeJsString(sanitizeFilePath(data.metadata.workspacePath)), generatedAt: sanitizeJsString(data.metadata.generatedAt), analyzerVersion: sanitizeJsString(data.metadata.analyzerVersion), }, } } /** * Generates the sidebar HTML with statistics and filter controls. * * @param data - Visualization data * @param title - Document title * @returns Sidebar HTML string */ function generateSidebarHtml(data: VisualizationData, title: string): string { const stats = data.statistics const layers = data.layers // Generate layer filter checkboxes const layerFiltersHtml = layers .map( layer => ` ${sanitizeHtml(layer.name)} ${stats.nodesByLayer[layer.name] ?? 0} `, ) .join('') // Generate severity statistics const severityStatsHtml = ['critical', 'error', 'warning', 'info'] .map( severity => `

${severity}

${stats.violationsBySeverity[severity as keyof typeof stats.violationsBySeverity] ?? 0}

`, ) .join('') return `

` } /** * Generates the control panel HTML. * * @returns Control panel HTML string */ function generateControlPanelHtml(): string { return `

View:

Search:

100%

` } /** * Validates visualization data before rendering. * * @param data - The data to validate * @returns Result indicating validity */ function validateVisualizationData(data: unknown): Result { if (data === null || data === undefined || typeof data !== 'object') { return err({ code: 'INVALID_DATA', message: 'Visualization data must be an object', }) } const d = data as Record if (!Array.isArray(d.nodes)) { return err({ code: 'INVALID_DATA', message: 'Visualization data must have a nodes array', }) } if (!Array.isArray(d.edges)) { return err({ code: 'INVALID_DATA', message: 'Visualization data must have an edges array', }) } if (d.statistics === null || d.statistics === undefined || typeof d.statistics !== 'object') { return err({ code: 'INVALID_DATA', message: 'Visualization data must have statistics object', }) } if (d.metadata === null || d.metadata === undefined || typeof d.metadata !== 'object') { return err({ code: 'INVALID_DATA', message: 'Visualization data must have metadata object', }) } return ok(data as VisualizationData) } /** * Renders visualization data as a self-contained HTML file. * * @param data - The visualization data to render * @param options - Render options * @returns Result containing the HTML string or an error */ export function renderVisualizationHtml( data: VisualizationData, options: Partial = {}, ): Result { // Merge options with defaults const opts: HtmlRenderOptions = { ...DEFAULT_HTML_RENDER_OPTIONS, ...options, } // Validate data const validationResult = validateVisualizationData(data) if (validationResult.success === false) { return validationResult } // Sanitize data for safe embedding const sanitizedData = sanitizeVisualizationData(data) // Serialize data for embedding const dataJson = JSON.stringify(sanitizedData) // Generate CSS const styles = generateStyles() // Generate sidebar and control panel const sidebarHtml = generateSidebarHtml(sanitizedData, opts.title) const controlPanelHtml = generateControlPanelHtml() // Generate JavaScript const graphScript = generateGraphInitScript() const controlScript = generateControlPanelScript() // Build the complete HTML document const html = ` ${sanitizeHtml(opts.title)}

${controlPanelHtml}

${opts.customJs === undefined ? '' : ` `} ` return ok(html) } /** * Generates a minimal HTML preview for testing. * * @param data - The visualization data * @param title - Document title * @returns A simplified HTML string for testing */ export function renderMinimalHtml(data: VisualizationData, title: string): string { const sanitizedData = sanitizeVisualizationData(data) return ` ${sanitizeHtml(title)}

${sanitizeHtml(title)}

Nodes: ${sanitizedData.statistics.totalNodes}

Edges: ${sanitizedData.statistics.totalEdges}

Cycles: ${sanitizedData.statistics.totalCycles}

` } /** * Exports visualization data as JSON. * * @param data - The visualization data to export * @returns JSON string representation */ export function exportVisualizationJson(data: VisualizationData): string { const sanitizedData = sanitizeVisualizationData(data) return JSON.stringify(sanitizedData, null, 2) } /** * Calculates the approximate size of the generated HTML in bytes. * * @param data - The visualization data * @returns Estimated size in bytes */ export function estimateHtmlSize(data: VisualizationData): number { // Base HTML structure + CSS + D3 library const baseSize = 50000 // ~50KB for D3 and styles // Data size (rough estimate) const dataJson = JSON.stringify(data) const dataSize = dataJson.length * 1.1 // Account for some expansion // Scripts const scriptsSize = 10000 // ~10KB for scripts return Math.ceil(baseSize + dataSize + scriptsSize) } /** * Checks if the data would produce an HTML file within size limits. * * @param data - The visualization data * @param maxSizeBytes - Maximum allowed size in bytes (default: 5MB) * @returns True if within limits */ export function isWithinSizeLimit( data: VisualizationData, maxSizeBytes: number = 5 * 1024 * 1024, ): boolean { return estimateHtmlSize(data) < maxSizeBytes }

${sanitizeHtml(title)}

Statistics

Violations by Severity

Filter by Severity

Filter by Layer

Legend

${sanitizeHtml(title)}