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

package/dist/errors/sanitizer.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Parameter and Content Sanitization
+ *
+ * Provides sanitization utilities for directive parameters, file paths,
+ * expressions, and component props.
+ *
+ * @module errors/sanitizer
+ */
+/**
+ * Options for parameter sanitization
+ */
+export interface SanitizeOptions {
+    /** Allow HTML in parameter values (default: false) */
+    allowHtml?: boolean;
+    /** Maximum length for string parameters (default: 10000) */
+    maxLength?: number;
+    /** Allow special characters (default: true for most, false for paths) */
+    allowSpecialChars?: boolean;
+    /** Custom sanitization function */
+    customSanitizer?: (value: string) => string;
+}
+/**
+ * Result of parameter sanitization
+ */
+export interface SanitizedParam {
+    /** Sanitized value */
+    value: string;
+    /** Whether the value was modified */
+    modified: boolean;
+    /** Warnings generated during sanitization */
+    warnings: string[];
+}
+/**
+ * Validation utilities
+ */
+export declare const validators: {
+    /**
+     * Validate file path is safe and doesn't escape the allowed directory
+     */
+    isValidFilePath(filePath: string, allowedDir?: string): boolean;
+    /**
+     * Validate template variable name
+     */
+    isValidVariableName(name: string): boolean;
+    /**
+     * Validate directive name
+     */
+    isValidDirectiveName(name: string): boolean;
+    /**
+     * Check if string contains potentially malicious content
+     */
+    isSafeContent(content: string): boolean;
+};
+/**
+ * Sanitize a directive parameter value
+ */
+export declare function sanitizeDirectiveParam(param: string, options?: SanitizeOptions): SanitizedParam;
+/**
+ * Sanitize a file path parameter
+ */
+export declare function sanitizeFilePath(filePath: string, baseDir?: string): string | null;
+/**
+ * Sanitize an expression parameter (used in @if, @foreach, etc.)
+ */
+export declare function sanitizeExpression(expr: string): SanitizedParam;
+/**
+ * Sanitize multiple directive parameters at once
+ */
+export declare function sanitizeDirectiveParams(params: string[], options?: SanitizeOptions): SanitizedParam[];
+/**
+ * Validate and sanitize component props
+ */
+export declare function sanitizeComponentProps(props: Record<string, unknown>): Record<string, unknown>;

package/dist/errors/sanitizer.js

@@ -0,0 +1,181 @@
+import path from "node:path";
+export const validators = {
+  isValidFilePath(filePath, allowedDir) {
+    const normalizedPath = filePath.replace(/\\/g, "/");
+    if (normalizedPath.includes("\x00"))
+      return !1;
+    if (normalizedPath.includes("../") || normalizedPath.includes("..\\") || normalizedPath === ".." || normalizedPath.startsWith("../") || normalizedPath.endsWith("/..") || normalizedPath.includes("/..\\") || normalizedPath.includes("\\../"))
+      return !1;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(normalizedPath))
+      return !1;
+    if (normalizedPath.startsWith("/")) {
+      if ([
+        "/etc/",
+        "/root/",
+        "/var/",
+        "/usr/",
+        "/bin/",
+        "/sbin/",
+        "/proc/",
+        "/sys/",
+        "/dev/",
+        "/boot/",
+        "/home/",
+        "/private/",
+        "/Library/",
+        "/System/"
+      ].some((p) => normalizedPath === p.slice(0, -1) || normalizedPath.startsWith(p)))
+        return !1;
+    }
+    if (/^[a-z]:/i.test(normalizedPath)) {
+      if ([
+        "Windows/",
+        "Windows\\",
+        "System32/",
+        "System32\\",
+        "Program Files/",
+        "Program Files\\"
+      ].some((p) => normalizedPath.includes(p)))
+        return !1;
+    }
+    if (allowedDir) {
+      const resolvedPath = path.resolve(allowedDir, filePath), normalizedAllowedDir = path.resolve(allowedDir);
+      if (!resolvedPath.startsWith(normalizedAllowedDir + path.sep) && resolvedPath !== normalizedAllowedDir)
+        return !1;
+    }
+    return !0;
+  },
+  isValidVariableName(name) {
+    return /^[a-z_$]\w*$/i.test(name);
+  },
+  isValidDirectiveName(name) {
+    return /^[a-z][\w-]*$/i.test(name);
+  },
+  isSafeContent(content) {
+    return ![
+      /<script[^>]*>[\s\S]*?<\/script>/i,
+      /javascript:/i,
+      /data:text\/html/i,
+      /vbscript:/i,
+      /on\w+\s*=/i
+    ].some((pattern) => pattern.test(content));
+  }
+};
+function escapeHtml(str) {
+  const htmlEntities = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;"
+  };
+  return str.replace(/[&<>"']/g, (char) => htmlEntities[char] || char);
+}
+export function sanitizeDirectiveParam(param, options = {}) {
+  const {
+    allowHtml = !1,
+    maxLength = 1e4,
+    allowSpecialChars = !0,
+    customSanitizer
+  } = options, warnings = [];
+  let value = param, modified = !1;
+  if (customSanitizer) {
+    const customResult = customSanitizer(value);
+    if (customResult !== value) {
+      value = customResult;
+      modified = !0;
+    }
+  }
+  if (value.includes("\x00")) {
+    value = value.replace(/\0/g, "");
+    modified = !0;
+    warnings.push("Null bytes removed from parameter");
+  }
+  if (value.length > maxLength) {
+    value = value.substring(0, maxLength);
+    modified = !0;
+    warnings.push(`Parameter truncated to ${maxLength} characters`);
+  }
+  if (!allowHtml && /<[^>]+>/.test(value)) {
+    value = escapeHtml(value);
+    modified = !0;
+    warnings.push("HTML content was escaped");
+  }
+  const dangerousPatterns = [
+    { pattern: /javascript:/gi, replacement: "", name: "javascript: URI" },
+    { pattern: /vbscript:/gi, replacement: "", name: "vbscript: URI" },
+    { pattern: /data:text\/html/gi, replacement: "", name: "data:text/html URI" }
+  ];
+  for (const { pattern, replacement, name } of dangerousPatterns)
+    if (pattern.test(value)) {
+      value = value.replace(pattern, replacement);
+      modified = !0;
+      warnings.push(`Removed ${name} from parameter`);
+    }
+  if (!allowSpecialChars) {
+    const originalValue = value;
+    value = value.split("").filter((char) => {
+      const code = char.charCodeAt(0);
+      return code >= 32 && code !== 127;
+    }).join("");
+    if (value !== originalValue) {
+      modified = !0;
+      warnings.push("Control characters removed");
+    }
+  }
+  return { value, modified, warnings };
+}
+export function sanitizeFilePath(filePath, baseDir) {
+  let sanitized = filePath.replace(/\0/g, "");
+  sanitized = sanitized.replace(/\\/g, "/");
+  sanitized = sanitized.replace(/^[a-z][a-z0-9+.-]*:/i, "");
+  while (sanitized.includes("../") || sanitized.includes("./"))
+    sanitized = sanitized.replace(/\.\.\//g, "").replace(/\.\//g, "");
+  if (!validators.isValidFilePath(sanitized, baseDir))
+    return null;
+  return sanitized;
+}
+export function sanitizeExpression(expr) {
+  const warnings = [];
+  let value = expr.trim(), modified = value !== expr;
+  const dangerousExprPatterns = [
+    { pattern: /\beval\s*\(/gi, name: "eval()" },
+    { pattern: /\bFunction\s*\(/gi, name: "Function()" },
+    { pattern: /\bsetTimeout\s*\(/gi, name: "setTimeout()" },
+    { pattern: /\bsetInterval\s*\(/gi, name: "setInterval()" },
+    { pattern: /\bimport\s*\(/gi, name: "dynamic import()" },
+    { pattern: /\brequire\s*\(/gi, name: "require()" },
+    { pattern: /\b__proto__\b/gi, name: "__proto__" },
+    { pattern: /\bconstructor\b/gi, name: "constructor" },
+    { pattern: /\bprototype\b/gi, name: "prototype" }
+  ];
+  for (const { pattern, name } of dangerousExprPatterns)
+    if (pattern.test(value))
+      warnings.push(`Potentially dangerous pattern detected: ${name}`);
+  if (value.includes("\x00")) {
+    value = value.replace(/\0/g, "");
+    modified = !0;
+    warnings.push("Null bytes removed from expression");
+  }
+  return { value, modified, warnings };
+}
+export function sanitizeDirectiveParams(params, options = {}) {
+  return params.map((param) => sanitizeDirectiveParam(param, options));
+}
+export function sanitizeComponentProps(props) {
+  const sanitized = {};
+  for (const [key, value] of Object.entries(props)) {
+    if (!validators.isValidVariableName(key))
+      continue;
+    if (typeof value === "string") {
+      const result = sanitizeDirectiveParam(value);
+      sanitized[key] = result.value;
+    } else if (Array.isArray(value))
+      sanitized[key] = value.map((item) => typeof item === "string" ? sanitizeDirectiveParam(item).value : item);
+    else if (typeof value === "object" && value !== null)
+      sanitized[key] = sanitizeComponentProps(value);
+    else
+      sanitized[key] = value;
+  }
+  return sanitized;
+}

package/dist/errors/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Error Types and Classes
+ *
+ * Custom error classes for better error classification and handling.
+ *
+ * @module errors/types
+ */
+import type { ErrorCode } from './codes';
+/**
+ * Error handling configuration
+ */
+export interface ErrorConfig {
+    /** Show relative paths instead of absolute (default: false) */
+    showRelativePaths: boolean;
+    /** Base directory for relative path calculation */
+    baseDir?: string;
+    /** Enable auto-recovery for common syntax errors (default: false in production) */
+    enableAutoRecovery: boolean;
+    /** Log warnings when auto-recovery is applied */
+    logRecoveryWarnings: boolean;
+}
+/**
+ * Configure error handling behavior
+ */
+export declare function configureErrorHandling(config: Partial<ErrorConfig>): void;
+/**
+ * Get current error configuration
+ */
+export declare function getErrorConfig(): ErrorConfig;
+/**
+ * Reset error configuration to defaults
+ */
+export declare function resetErrorConfig(): void;
+/**
+ * Format file path based on configuration
+ */
+export declare function formatFilePath(filePath: string): string;
+/**
+ * Base STX error class
+ */
+export declare class StxError extends Error {
+    code: string;
+    filePath?: string | undefined;
+    line?: number | undefined;
+    column?: number | undefined;
+    context?: string | undefined;
+    /** Numeric error code for programmatic handling */
+    numericCode: ErrorCode;
+    constructor(message: string, code: string, filePath?: string | undefined, line?: number | undefined, column?: number | undefined, context?: string | undefined, numericCode?: ErrorCode);
+}
+/**
+ * Syntax error in template
+ */
+export declare class StxSyntaxError extends StxError {
+    constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+}
+/**
+ * Runtime error during template processing
+ */
+export declare class StxRuntimeError extends StxError {
+    constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+}
+/**
+ * Security-related error
+ */
+export declare class StxSecurityError extends StxError {
+    constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+}
+/**
+ * File operation error
+ */
+export declare class StxFileError extends StxError {
+    constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+}
+/**
+ * Validation error - these are ALWAYS fatal and cannot be recovered from.
+ * Used for enforcing coding standards like prohibited DOM API usage.
+ */
+export declare class StxValidationError extends StxError {
+    /** Validation errors are always fatal and should never be caught/recovered */
+    readonly isFatal: boolean;
+    constructor(message: string, filePath?: string, line?: number, column?: number, context?: string, numericCode?: ErrorCode);
+}
+/**
+ * Error context information
+ */
+export interface ErrorContext {
+    filePath: string;
+    template: string;
+    offset: number;
+    match: string;
+}

package/dist/errors/types.js

@@ -0,0 +1,86 @@
+import path from "node:path";
+import { isDevelopment } from "../env.js";
+import { ErrorCodes } from "./codes.js";
+const defaultErrorConfig = {
+  showRelativePaths: !1,
+  enableAutoRecovery: isDevelopment(),
+  logRecoveryWarnings: !0
+};
+let currentErrorConfig = { ...defaultErrorConfig };
+export function configureErrorHandling(config) {
+  currentErrorConfig = { ...currentErrorConfig, ...config };
+}
+export function getErrorConfig() {
+  return { ...currentErrorConfig };
+}
+export function resetErrorConfig() {
+  currentErrorConfig = { ...defaultErrorConfig };
+}
+export function formatFilePath(filePath) {
+  if (!currentErrorConfig.showRelativePaths || !filePath)
+    return filePath;
+  const baseDir = currentErrorConfig.baseDir || process.cwd();
+  try {
+    const relativePath = path.relative(baseDir, filePath);
+    return relativePath.startsWith("..") ? filePath : relativePath;
+  } catch {
+    return filePath;
+  }
+}
+
+export class StxError extends Error {
+  code;
+  filePath;
+  line;
+  column;
+  context;
+  numericCode;
+  constructor(message, code, filePath, line, column, context, numericCode) {
+    super(message);
+    this.code = code;
+    this.filePath = filePath;
+    this.line = line;
+    this.column = column;
+    this.context = context;
+    this.name = "StxError";
+    this.numericCode = numericCode || ErrorCodes.EVALUATION_ERROR;
+    if (this.filePath)
+      this.filePath = formatFilePath(this.filePath);
+  }
+}
+
+export class StxSyntaxError extends StxError {
+  constructor(message, filePath, line, column, context, numericCode) {
+    super(message, "stx_SYNTAX_ERROR", filePath, line, column, context, numericCode || ErrorCodes.INVALID_DIRECTIVE_SYNTAX);
+    this.name = "StxSyntaxError";
+  }
+}
+
+export class StxRuntimeError extends StxError {
+  constructor(message, filePath, line, column, context, numericCode) {
+    super(message, "stx_RUNTIME_ERROR", filePath, line, column, context, numericCode || ErrorCodes.EVALUATION_ERROR);
+    this.name = "StxRuntimeError";
+  }
+}
+
+export class StxSecurityError extends StxError {
+  constructor(message, filePath, line, column, context, numericCode) {
+    super(message, "stx_SECURITY_ERROR", filePath, line, column, context, numericCode || ErrorCodes.UNSAFE_EXPRESSION);
+    this.name = "StxSecurityError";
+  }
+}
+
+export class StxFileError extends StxError {
+  constructor(message, filePath, line, column, context, numericCode) {
+    super(message, "stx_FILE_ERROR", filePath, line, column, context, numericCode || ErrorCodes.FILE_NOT_FOUND);
+    this.name = "StxFileError";
+  }
+}
+
+export class StxValidationError extends StxError {
+  isFatal = !0;
+  constructor(message, filePath, line, column, context, numericCode) {
+    super(message, "stx_VALIDATION_ERROR", filePath, line, column, context, numericCode || ErrorCodes.DOM_API_VIOLATION);
+    this.name = "StxValidationError";
+  }
+}

package/dist/events.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Event Directives Module
+ *
+ * Provides Alpine.js-style event handling for STX templates.
+ * Transforms `@click`, `@keydown.enter`, etc. into client-side event listeners.
+ *
+ * ## Supported Syntax
+ *
+ * ### Basic Events
+ * ```html
+ * <button @click="count++">Increment</button>
+ * <button @click="handleClick()">Click me</button>
+ * <form @submit="handleSubmit()">...</form>
+ * ```
+ *
+ * ### Event Modifiers
+ * ```html
+ * <form @submit.prevent="handleSubmit()">...</form>
+ * <a @click.prevent.stop="navigate()">Link</a>
+ * <button @click.once="initialize()">Init</button>
+ * <div @click.self="onlyThis()">...</div>
+ * <input @keydown.capture="log()">
+ * ```
+ *
+ * ### Key Modifiers
+ * ```html
+ * <input @keydown.enter="submit()">
+ * <input @keyup.escape="cancel()">
+ * <input @keydown.space="toggle()">
+ * <input @keydown.ctrl.s="save()">
+ * <input @keydown.meta.enter="send()">
+ * ```
+ *
+ * ### Mouse Modifiers
+ * ```html
+ * <div @click.left="handleLeft()">
+ * <div @click.right="handleRight()">
+ * <div @click.middle="handleMiddle()">
+ * ```
+ *
+ * ### Special Variables
+ * ```html
+ * <input @input="value = $event.target.value">
+ * <button @click="handleClick($el)">Uses element</button>
+ * ```
+ *
+ * @module events
+ */
+export interface ParsedEvent {
+    /** Original attribute string (e.g., "@click.prevent") */
+    attribute: string;
+    /** Event name (e.g., "click", "keydown") */
+    event: string;
+    /** Handler expression (e.g., "count++", "handleClick()") */
+    handler: string;
+    /** Event modifiers */
+    modifiers: EventModifiers;
+    /** Unique element ID for binding */
+    elementId: string;
+}
+export interface EventModifiers {
+    /** Call preventDefault() */
+    prevent: boolean;
+    /** Call stopPropagation() */
+    stop: boolean;
+    /** Only fire once */
+    once: boolean;
+    /** Use capture mode */
+    capture: boolean;
+    /** Only fire if event.target === element */
+    self: boolean;
+    /** Passive event listener */
+    passive: boolean;
+    /** Key modifiers (enter, escape, space, etc.) */
+    keys: string[];
+    /** System modifiers (ctrl, alt, shift, meta) */
+    systemKeys: string[];
+    /** Mouse button (left, right, middle) */
+    mouse: string | null;
+    /** Debounce delay in ms */
+    debounce: number | null;
+    /** Throttle delay in ms */
+    throttle: number | null;
+}
+/**
+ * `@click="doThing"` names a function, so it must be INVOKED — not evaluated.
+ *
+ * The declarative runtime learned this in #1695: without it the expression falls
+ * through to a generic `new Function` and runs as a discarded identifier
+ * statement, so the click silently does nothing. Every IMPERATIVE binding path
+ * still evaluated it, in three separate places — the inline `else` branch
+ * emitted by client-script.ts, the `__stx_runHandler` fallback below, and
+ * `__stx_execute` in the x-data bridge — so the declarative path disagreed with
+ * all three (#1824).
+ *
+ * Normalising here, at emit time, rather than inside each of those runtimes:
+ * the handler text is already known when it is emitted, so one transform covers
+ * every path, and the rule stays out of the generated template literals.
+ *
+ * Restricted to a plain identifier, matching the runtime's own check exactly —
+ * a dotted path would require `obj` to exist before `typeof obj.fn` could be
+ * asked. The `_isSignal` exclusion is the runtime's too, and it matters because
+ * signals ARE functions: without it `@click="count"` would read the signal
+ * instead of doing nothing.
+ */
+export declare function asInvocableStatement(handler: string): string;
+/**
+ * Generate the complete runtime script
+ */
+export declare function generateRuntimeScript(events: ParsedEvent[]): string;
+/**
+ * Extract and process event attributes from a template without generating
+ * a standalone script. Returns the modified template (with @event attributes
+ * removed and IDs added) and the collected event bindings as data.
+ *
+ * Used by SFC processing to inject event bindings into the component's
+ * <script client> scope instead of a separate script block.
+ *
+ * @param template - The HTML template string
+ * @returns Object with processed template and collected bindings
+ */
+export declare function extractAndProcessEvents(template: string): {
+    template: string;
+    bindings: ParsedEvent[];
+};
+/**
+ * Process event directives in a template.
+ *
+ * Transforms `@click`, `@keydown.enter`, etc. attributes into
+ * client-side event listeners.
+ *
+ * In SFC mode (context.__stx_sfc_mode), event bindings are collected
+ * on context.__stx_event_bindings instead of generating a standalone script.
+ * This allows them to be injected into the component's <script client> scope.
+ *
+ * @param template - The HTML template string
+ * @param context - Template context
+ * @param filePath - Source file path for error messages
+ * @returns Processed template with event binding script (or just template in SFC mode)
+ */
+export declare function processEventDirectives(template: string, context: Record<string, unknown>, _filePath: string): string;
+/**
+ * Check if a template contains event directives
+ */
+export declare function hasEventDirectives(template: string): boolean;