@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/errors/formatter.js

@@ -0,0 +1,196 @@
+import { getErrorCodeName } from "./codes.js";
+import { formatFilePath } from "./types.js";
+export function formatError(options) {
+  const {
+    type,
+    message,
+    code,
+    filePath,
+    line,
+    column,
+    template,
+    offset,
+    snippet,
+    suggestion,
+    format = "text"
+  } = options;
+  let actualLine = line, actualColumn = column;
+  if (!actualLine && template && offset !== void 0) {
+    const position = getLineAndColumn(template, offset);
+    actualLine = position.line;
+    actualColumn = position.column;
+  }
+  const displayPath = filePath ? formatFilePath(filePath) : void 0, codeName = code ? getErrorCodeName(code) : void 0, data = {
+    type,
+    code,
+    codeName,
+    message,
+    filePath: displayPath,
+    line: actualLine,
+    column: actualColumn,
+    snippet,
+    suggestion,
+    timestamp: new Date().toISOString()
+  };
+  let formatted;
+  switch (format) {
+    case "html":
+      formatted = formatErrorAsHtml(data);
+      break;
+    case "json":
+      formatted = JSON.stringify(data, null, 2);
+      break;
+    case "console":
+      formatted = formatErrorAsConsole(data, template, offset);
+      break;
+    case "text":
+    default:
+      formatted = formatErrorAsText(data, template, offset);
+      break;
+  }
+  return { formatted, data };
+}
+function formatErrorAsText(data, template, _offset) {
+  const parts = [], codeStr = data.code ? ` [${data.codeName || data.code}]` : "";
+  parts.push(`[${data.type} Error${codeStr}]`);
+  if (data.filePath) {
+    let location = data.filePath;
+    if (data.line) {
+      location += `:${data.line}`;
+      if (data.column)
+        location += `:${data.column}`;
+    }
+    parts.push(`at ${location}`);
+  }
+  parts.push(`
+${data.message}`);
+  if (template && data.line) {
+    const contextLines = getContextLines(template, data.line, 2);
+    if (contextLines)
+      parts.push(`
+${contextLines}`);
+  }
+  if (data.snippet)
+    parts.push(`
+Snippet: ${data.snippet}`);
+  if (data.suggestion)
+    parts.push(`
+Suggestion: ${data.suggestion}`);
+  return parts.join(" ");
+}
+function formatErrorAsHtml(data) {
+  const codeStr = data.code ? ` [${data.code}]` : "", locationStr = data.filePath ? ` in ${data.filePath}${data.line ? `:${data.line}` : ""}` : "";
+  let html = `<!-- [${data.type} Error${codeStr}]${locationStr}: ${escapeHtmlComment(data.message)}`;
+  if (data.suggestion)
+    html += ` | Suggestion: ${escapeHtmlComment(data.suggestion)}`;
+  html += " -->";
+  return html;
+}
+function formatErrorAsConsole(data, template, _offset) {
+  const red = "\x1B[31m", yellow = "\x1B[33m", cyan = "\x1B[36m", gray = "\x1B[90m", bold = "\x1B[1m", reset = "\x1B[0m", parts = [], codeStr = data.code ? ` [${data.codeName || data.code}]` : "";
+  parts.push(`${bold}${red}\u2501\u2501\u2501 ${data.type} Error${codeStr} \u2501\u2501\u2501${reset}`);
+  if (data.filePath) {
+    let location = `${cyan}${data.filePath}${reset}`;
+    if (data.line) {
+      location += `${gray}:${data.line}${reset}`;
+      if (data.column)
+        location += `${gray}:${data.column}${reset}`;
+    }
+    parts.push(`
+${gray}at${reset} ${location}`);
+  }
+  parts.push(`
+
+${data.message}`);
+  if (template && data.line) {
+    const contextLines = getContextLinesColored(template, data.line, 2);
+    if (contextLines)
+      parts.push(`
+
+${gray}Context:${reset}
+${contextLines}`);
+  }
+  if (data.suggestion)
+    parts.push(`
+
+${yellow}Suggestion:${reset} ${data.suggestion}`);
+  parts.push(`
+${red}\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501${reset}`);
+  return parts.join("");
+}
+function getContextLines(template, errorLine, contextSize) {
+  const lines = template.split(`
+`), startLine = Math.max(0, errorLine - contextSize - 1), endLine = Math.min(lines.length - 1, errorLine + contextSize - 1), result = [];
+  for (let i = startLine;i <= endLine; i++) {
+    const lineNum = (i + 1).toString().padStart(4), indicator = i === errorLine - 1 ? ">" : " ";
+    result.push(`${indicator}${lineNum} | ${lines[i]}`);
+  }
+  return result.join(`
+`);
+}
+function getContextLinesColored(template, errorLine, contextSize) {
+  const lines = template.split(`
+`), startLine = Math.max(0, errorLine - contextSize - 1), endLine = Math.min(lines.length - 1, errorLine + contextSize - 1), gray = "\x1B[90m", red = "\x1B[31m", reset = "\x1B[0m", result = [];
+  for (let i = startLine;i <= endLine; i++) {
+    const lineNum = (i + 1).toString().padStart(4), isErrorLine = i === errorLine - 1, indicator = isErrorLine ? `${red}>${reset}` : " ", lineContent = isErrorLine ? `${red}${lines[i]}${reset}` : `${gray}${lines[i]}${reset}`;
+    result.push(`${indicator}${gray}${lineNum}${reset} | ${lineContent}`);
+  }
+  return result.join(`
+`);
+}
+function escapeHtmlComment(str) {
+  return str.replace(/--/g, "- -").replace(/>/g, "&gt;");
+}
+function getLineAndColumn(text, offset) {
+  const lines = text.substring(0, offset).split(`
+`);
+  return {
+    line: lines.length,
+    column: lines[lines.length - 1].length
+  };
+}
+export function inlineError(type, message, code) {
+  return formatError({ type, message, code, format: "html" }).formatted;
+}
+export function consoleError(type, message, filePath, line, code) {
+  return formatError({ type, message, code, filePath, line, format: "console" }).formatted;
+}
+export function createEnhancedError(type, message, context) {
+  const lines = context.template.split(`
+`), position = getLineAndColumn(context.template, context.offset);
+  let errorOutput = `[${type} Error at line ${position.line} in ${context.filePath}]: ${message}
+
+`;
+  const startLine = Math.max(0, position.line - 3), endLine = Math.min(lines.length - 1, position.line + 2);
+  errorOutput += `Context:
+`;
+  for (let i = startLine;i <= endLine; i++) {
+    const lineNum = i + 1, line = lines[i] || "", indicator = i === position.line - 1 ? ">" : " ";
+    errorOutput += `${indicator} ${lineNum.toString().padStart(3)}: ${line}
+`;
+  }
+  if (position.line - 1 < lines.length) {
+    const padding = " ".repeat(position.column + 5);
+    errorOutput += `${padding}^
+`;
+  }
+  return errorOutput;
+}
+export function safeExecute(operation, fallback, errorHandler) {
+  try {
+    return operation();
+  } catch (error) {
+    if (errorHandler && error instanceof Error)
+      errorHandler(error);
+    return fallback;
+  }
+}
+export async function safeExecuteAsync(operation, fallback, errorHandler) {
+  try {
+    return await operation();
+  } catch (error) {
+    if (errorHandler && error instanceof Error)
+      errorHandler(error);
+    return fallback;
+  }
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Error Handling Module
+ *
+ * Provides comprehensive error handling utilities for the stx framework.
+ *
+ * @module errors
+ */
+export { clearErrorMessages, type ErrorCode, ErrorCodes, type ErrorMessages, type ErrorMessageTemplate, formatLocalizedError, getErrorCodeName, getErrorLocale, getErrorMessage, registerErrorMessages, setErrorLocale, } from './codes';
+export { consoleError, createEnhancedError, type ErrorMessageOptions, type ErrorOutputFormat, formatError, inlineError, safeExecute, safeExecuteAsync, type StandardizedError, } from './formatter';
+export { devHelpers, type ErrorLogEntry, ErrorLogger, errorLogger, type ErrorLoggerOptions, errorRecovery, } from './logger';
+export { sanitizeComponentProps, sanitizeDirectiveParam, sanitizeDirectiveParams, type SanitizedParam, sanitizeExpression, sanitizeFilePath, type SanitizeOptions, validators, } from './sanitizer';
+export { configureErrorHandling, type ErrorConfig, type ErrorContext, formatFilePath, getErrorConfig, resetErrorConfig, StxError, StxFileError, StxRuntimeError, StxSecurityError, StxSyntaxError, StxValidationError, } from './types';

package/dist/errors/index.js

@@ -0,0 +1,44 @@
+export {
+  clearErrorMessages,
+  ErrorCodes,
+  formatLocalizedError,
+  getErrorCodeName,
+  getErrorLocale,
+  getErrorMessage,
+  registerErrorMessages,
+  setErrorLocale
+} from "./codes.js";
+export {
+  consoleError,
+  createEnhancedError,
+  formatError,
+  inlineError,
+  safeExecute,
+  safeExecuteAsync
+} from "./formatter.js";
+export {
+  devHelpers,
+  ErrorLogger,
+  errorLogger,
+  errorRecovery
+} from "./logger.js";
+export {
+  sanitizeComponentProps,
+  sanitizeDirectiveParam,
+  sanitizeDirectiveParams,
+  sanitizeExpression,
+  sanitizeFilePath,
+  validators
+} from "./sanitizer.js";
+export {
+  configureErrorHandling,
+  formatFilePath,
+  getErrorConfig,
+  resetErrorConfig,
+  StxError,
+  StxFileError,
+  StxRuntimeError,
+  StxSecurityError,
+  StxSyntaxError,
+  StxValidationError
+} from "./types.js";

package/dist/errors/logger.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Error Logger and Recovery
+ *
+ * Provides error logging, recovery strategies, and development helpers.
+ *
+ * @module errors/logger
+ */
+/**
+ * Error recovery strategies
+ *
+ * NOTE: Auto-recovery is opt-in via configuration.
+ * Use configureErrorHandling({ enableAutoRecovery: true }) to enable.
+ */
+export interface ErrorRecovery {
+    isEnabled(): boolean;
+    fixCommonSyntaxErrors(template: string): {
+        fixed: string;
+        fixes: string[];
+    };
+    createFallbackContent(sectionType: string, error: Error): string;
+}
+export declare const errorRecovery: ErrorRecovery;
+/**
+ * Error logger configuration options
+ */
+export interface ErrorLoggerOptions {
+    /** Maximum number of errors to keep in memory (default: 1000) */
+    maxErrors?: number;
+    /** Enable file logging */
+    enableFileLogging?: boolean;
+    /** Path to log file (default: '.stx/errors.log') */
+    logFilePath?: string;
+    /** Log format: 'json' for structured logs, 'text' for human-readable (default: 'json') */
+    logFormat?: 'json' | 'text';
+    /** Maximum log file size in bytes before rotation (default: 10MB) */
+    maxFileSize?: number;
+    /** Number of rotated log files to keep (default: 5) */
+    maxLogFiles?: number;
+    /** Minimum error level to log to file: 'all', 'error', 'warning' (default: 'all') */
+    minLevel?: 'all' | 'error' | 'warning';
+}
+/**
+ * Error log entry structure
+ */
+export interface ErrorLogEntry {
+    timestamp: Date;
+    error: Error;
+    context?: unknown;
+    level?: 'error' | 'warning' | 'info';
+}
+/**
+ * Error logging and monitoring with optional file persistence
+ */
+export declare class ErrorLogger {
+    private errors;
+    private maxErrors;
+    private enableFileLogging;
+    private logFilePath;
+    private logFormat;
+    private maxFileSize;
+    private maxLogFiles;
+    private minLevel;
+    private writeQueue;
+    constructor(options?: ErrorLoggerOptions);
+    /**
+     * Configure the error logger
+     */
+    configure(options: ErrorLoggerOptions): void;
+    /**
+     * Log an error with optional context
+     */
+    log(error: Error, context?: unknown, level?: 'error' | 'warning' | 'info'): void;
+    /**
+     * Check if error level should be logged based on minLevel setting
+     */
+    private shouldLog;
+    /**
+     * Format an error entry for logging
+     */
+    private formatEntry;
+    /**
+     * Write error entry to file (async, non-blocking)
+     */
+    private writeToFile;
+    /**
+     * Rotate log files if current file exceeds max size
+     */
+    private rotateIfNeeded;
+    /**
+     * Get recent errors from memory
+     */
+    getRecentErrors(limit?: number): ErrorLogEntry[];
+    /**
+     * Get errors filtered by type
+     */
+    getErrorsByType(errorType: string): ErrorLogEntry[];
+    /**
+     * Get errors filtered by level
+     */
+    getErrorsByLevel(level: 'error' | 'warning' | 'info'): ErrorLogEntry[];
+    /**
+     * Clear all errors from memory
+     */
+    clear(): void;
+    /**
+     * Clear log file
+     */
+    clearLogFile(): Promise<void>;
+    /**
+     * Get error statistics
+     */
+    getStats(): {
+        total: number;
+        byType: Record<string, number>;
+        byLevel: Record<string, number>;
+    };
+    /**
+     * Export errors to a file (for debugging/reporting)
+     */
+    exportToFile(filePath: string, format?: 'json' | 'text'): Promise<void>;
+    /**
+     * Wait for all pending writes to complete
+     */
+    flush(): Promise<void>;
+}
+export declare const errorLogger: ErrorLogger;
+/**
+ * Development mode helpers
+ */
+export interface DevHelpers {
+    isDevelopment(): boolean;
+    logDetailedError(error: Error, context?: unknown): void;
+    createErrorReport(error: Error, context?: unknown): string;
+}
+export declare const devHelpers: DevHelpers;

package/dist/errors/logger.js

@@ -0,0 +1,250 @@
+import { isDevelopment } from "../env.js";
+import { getErrorConfig } from "./types.js";
+export const errorRecovery = {
+  isEnabled() {
+    return getErrorConfig().enableAutoRecovery;
+  },
+  fixCommonSyntaxErrors(template) {
+    const config = getErrorConfig();
+    if (!config.enableAutoRecovery)
+      return { fixed: template, fixes: [] };
+    let fixed = template;
+    const fixes = [], openBraces = (fixed.match(/\{\{/g) || []).length, closeBraces = (fixed.match(/\}\}/g) || []).length;
+    if (openBraces > closeBraces) {
+      const missing = openBraces - closeBraces;
+      fixed += "}}".repeat(missing);
+      fixes.push(`Added ${missing} missing closing braces '}}'`);
+    }
+    const unclosedDirectives = ["if", "foreach", "for", "switch", "section"];
+    for (const directive of unclosedDirectives) {
+      const openCount = (fixed.match(new RegExp(`@${directive}\\b`, "g")) || []).length, closeCount = (fixed.match(new RegExp(`@end${directive}\\b`, "g")) || []).length;
+      if (openCount > closeCount) {
+        const missing = openCount - closeCount;
+        for (let i = 0;i < missing; i++)
+          fixed += `
+@end${directive}`;
+        fixes.push(`Added ${missing} missing @end${directive}`);
+      }
+    }
+    if (fixes.length > 0 && config.logRecoveryWarnings) {
+      console.warn("[stx] Auto-recovery applied fixes:");
+      fixes.forEach((fix) => console.warn(`  - ${fix}`));
+      console.warn("  Consider fixing these issues in your template.");
+    }
+    return { fixed, fixes };
+  },
+  createFallbackContent(sectionType, error) {
+    if (isDevelopment())
+      return `<!-- ${sectionType} failed: ${error.message} -->`;
+    return "<!-- stx rendering error -->";
+  }
+};
+
+export class ErrorLogger {
+  errors = [];
+  maxErrors;
+  enableFileLogging;
+  logFilePath;
+  logFormat;
+  maxFileSize;
+  maxLogFiles;
+  minLevel;
+  writeQueue = Promise.resolve();
+  constructor(options = {}) {
+    this.maxErrors = options.maxErrors ?? 1000;
+    this.enableFileLogging = options.enableFileLogging ?? !1;
+    this.logFilePath = options.logFilePath ?? ".stx/errors.log";
+    this.logFormat = options.logFormat ?? "json";
+    this.maxFileSize = options.maxFileSize ?? 10485760;
+    this.maxLogFiles = options.maxLogFiles ?? 5;
+    this.minLevel = options.minLevel ?? "all";
+  }
+  configure(options) {
+    if (options.maxErrors !== void 0)
+      this.maxErrors = options.maxErrors;
+    if (options.enableFileLogging !== void 0)
+      this.enableFileLogging = options.enableFileLogging;
+    if (options.logFilePath !== void 0)
+      this.logFilePath = options.logFilePath;
+    if (options.logFormat !== void 0)
+      this.logFormat = options.logFormat;
+    if (options.maxFileSize !== void 0)
+      this.maxFileSize = options.maxFileSize;
+    if (options.maxLogFiles !== void 0)
+      this.maxLogFiles = options.maxLogFiles;
+    if (options.minLevel !== void 0)
+      this.minLevel = options.minLevel;
+  }
+  log(error, context, level = "error") {
+    const entry = {
+      timestamp: new Date,
+      error,
+      context,
+      level
+    };
+    this.errors.push(entry);
+    if (this.errors.length > this.maxErrors)
+      this.errors = this.errors.slice(-this.maxErrors);
+    if (this.enableFileLogging && this.shouldLog(level))
+      this.writeToFile(entry);
+  }
+  shouldLog(level) {
+    if (this.minLevel === "all")
+      return !0;
+    if (this.minLevel === "warning")
+      return level === "error" || level === "warning";
+    if (this.minLevel === "error")
+      return level === "error";
+    return !0;
+  }
+  formatEntry(entry) {
+    if (this.logFormat === "json")
+      return JSON.stringify({
+        timestamp: entry.timestamp.toISOString(),
+        level: entry.level || "error",
+        type: entry.error.constructor.name,
+        message: entry.error.message,
+        stack: entry.error.stack,
+        context: entry.context
+      });
+    const lines = [
+      `[${entry.timestamp.toISOString()}] [${(entry.level || "error").toUpperCase()}] ${entry.error.constructor.name}: ${entry.error.message}`
+    ];
+    if (entry.error.stack)
+      lines.push(`  Stack: ${entry.error.stack.split(`
+`).slice(1).join(`
+  `)}`);
+    if (entry.context)
+      lines.push(`  Context: ${JSON.stringify(entry.context)}`);
+    return lines.join(`
+`);
+  }
+  writeToFile(entry) {
+    this.writeQueue = this.writeQueue.then(async () => {
+      try {
+        const fs = await import("node:fs"), dir = (await import("node:path")).dirname(this.logFilePath);
+        if (!fs.existsSync(dir))
+          fs.mkdirSync(dir, { recursive: !0 });
+        await this.rotateIfNeeded(fs);
+        const logLine = `${this.formatEntry(entry)}
+`;
+        fs.appendFileSync(this.logFilePath, logLine, "utf-8");
+      } catch (err) {
+        if (process.env.STX_DEBUG === "true")
+          console.error("Failed to write to error log:", err);
+      }
+    });
+  }
+  async rotateIfNeeded(fs) {
+    try {
+      if (!fs.existsSync(this.logFilePath))
+        return;
+      if (fs.statSync(this.logFilePath).size < this.maxFileSize)
+        return;
+      for (let i = this.maxLogFiles - 1;i >= 1; i--) {
+        const oldPath = `${this.logFilePath}.${i}`, newPath = `${this.logFilePath}.${i + 1}`;
+        if (fs.existsSync(oldPath))
+          if (i >= this.maxLogFiles - 1)
+            fs.unlinkSync(oldPath);
+          else
+            fs.renameSync(oldPath, newPath);
+      }
+      if (this.maxLogFiles <= 1)
+        fs.writeFileSync(this.logFilePath, "");
+      else
+        fs.renameSync(this.logFilePath, `${this.logFilePath}.1`);
+    } catch (err) {
+      if (process.env.STX_DEBUG === "true")
+        console.error("Failed to rotate error logs:", err);
+    }
+  }
+  getRecentErrors(limit = 10) {
+    return this.errors.slice(-limit);
+  }
+  getErrorsByType(errorType) {
+    return this.errors.filter((item) => item.error.constructor.name === errorType);
+  }
+  getErrorsByLevel(level) {
+    return this.errors.filter((item) => item.level === level);
+  }
+  clear() {
+    this.errors.length = 0;
+  }
+  async clearLogFile() {
+    try {
+      const fs = await import("node:fs");
+      if (fs.existsSync(this.logFilePath))
+        fs.writeFileSync(this.logFilePath, "", "utf-8");
+    } catch (err) {
+      if (process.env.STX_DEBUG === "true")
+        console.error("Failed to clear error log:", err);
+    }
+  }
+  getStats() {
+    const byType = {}, byLevel = { error: 0, warning: 0, info: 0 };
+    for (const item of this.errors) {
+      const type = item.error.constructor.name;
+      byType[type] = (byType[type] || 0) + 1;
+      const level = item.level || "error";
+      byLevel[level] = (byLevel[level] || 0) + 1;
+    }
+    return {
+      total: this.errors.length,
+      byType,
+      byLevel
+    };
+  }
+  async exportToFile(filePath, format = "json") {
+    const fs = await import("node:fs"), dir = (await import("node:path")).dirname(filePath);
+    if (!fs.existsSync(dir))
+      fs.mkdirSync(dir, { recursive: !0 });
+    if (format === "json") {
+      const data = this.errors.map((entry) => ({
+        timestamp: entry.timestamp.toISOString(),
+        level: entry.level || "error",
+        type: entry.error.constructor.name,
+        message: entry.error.message,
+        stack: entry.error.stack,
+        context: entry.context
+      }));
+      fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+    } else {
+      const lines = this.errors.map((entry) => this.formatEntry(entry));
+      fs.writeFileSync(filePath, lines.join(`
+
+`), "utf-8");
+    }
+  }
+  async flush() {
+    await this.writeQueue;
+  }
+}
+export const errorLogger = new ErrorLogger, devHelpers = {
+  isDevelopment() {
+    return isDevelopment();
+  },
+  logDetailedError(error, context) {
+    if (!this.isDevelopment())
+      return;
+    console.error("=== stx Detailed Error ===");
+    console.error("Error:", error.message);
+    console.error("Stack:", error.stack);
+    if (context)
+      console.error("Context:", context);
+    console.error("========================");
+  },
+  createErrorReport(error, context) {
+    const report = [
+      "=== stx Error Report ===",
+      `Time: ${new Date().toISOString()}`,
+      `Error: ${error.message}`,
+      `Type: ${error.constructor.name}`,
+      `Stack: ${error.stack}`
+    ];
+    if (context)
+      report.push(`Context: ${JSON.stringify(context, null, 2)}`);
+    report.push("========================");
+    return report.join(`
+`);
+  }
+};