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

package/dist/validator.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Template Validation
+ *
+ * Provides validation utilities for stx templates before processing.
+ * Checks for common syntax errors, structural issues, and potential security problems.
+ */
+/**
+ * Template validation error
+ */
+export interface TemplateValidationError {
+    type: 'syntax' | 'directive' | 'expression' | 'structure';
+    message: string;
+    line?: number;
+    column?: number;
+    suggestion?: string;
+}
+/**
+ * Template validation result
+ */
+export interface TemplateValidationResult {
+    valid: boolean;
+    errors: TemplateValidationError[];
+    warnings: TemplateValidationError[];
+}
+/**
+ * Validate a template before processing
+ *
+ * Checks for common syntax errors and structural issues:
+ * - Unclosed directive blocks (@if without @endif)
+ * - Unclosed expression brackets
+ * - Invalid directive syntax
+ * - Nested quote issues
+ * - Security-related patterns
+ *
+ * @param template - The template string to validate
+ * @returns Validation result with errors and warnings
+ *
+ * @example
+ * ```typescript
+ * const result = validateTemplate(templateString)
+ * if (!result.valid) {
+ *   console.error('Template errors:', result.errors)
+ * }
+ * ```
+ */
+export declare function validateTemplate(template: string): TemplateValidationResult;
+/**
+ * Get line and column information for a position in the template
+ *
+ * @param template - The template string
+ * @param position - Character position
+ * @returns Line and column numbers (1-indexed)
+ */
+export declare function getPositionInfo(template: string, position: number): {
+    line: number;
+    column: number;
+};
+/**
+ * Validate a specific directive's syntax
+ *
+ * @param directiveName - Name of the directive (without @)
+ * @param content - Content between directive tags
+ * @param params - Parameters passed to the directive
+ * @returns Validation errors, if any
+ */
+export declare function validateDirective(directiveName: string, content: string, params: string[]): TemplateValidationError[];
+/**
+ * Check if a template has any directives
+ *
+ * @param template - The template string
+ * @returns Whether the template contains any stx directives
+ */
+export declare function hasDirectives(template: string): boolean;
+/**
+ * Extract all directive names used in a template
+ *
+ * @param template - The template string
+ * @returns Array of directive names (without @ prefix)
+ */
+export declare function extractDirectiveNames(template: string): string[];

package/dist/validator.js

@@ -0,0 +1,171 @@
+const DIRECTIVE_PAIRS = [
+  { open: "@if", close: "@endif", name: "if" },
+  { open: "@unless", close: "@endunless", name: "unless" },
+  { open: "@foreach", close: "@endforeach", name: "foreach" },
+  { open: "@for", close: "@endfor", name: "for" },
+  { open: "@while", close: "@endwhile", name: "while" },
+  { open: "@forelse", close: "@endforelse", name: "forelse" },
+  { open: "@switch", close: "@endswitch", name: "switch" },
+  { open: "@isset", close: "@endisset", name: "isset" },
+  { open: "@empty", close: "@endempty", name: "empty" },
+  { open: "@auth", close: "@endauth", name: "auth" },
+  { open: "@guest", close: "@endguest", name: "guest" },
+  { open: "@can", close: "@endcan", name: "can" },
+  { open: "@cannot", close: "@endcannot", name: "cannot" },
+  { open: "@section", close: "@endsection", name: "section", altClose: "@show" },
+  { open: "@push", close: "@endpush", name: "push" },
+  { open: "@prepend", close: "@endprepend", name: "prepend" },
+  { open: "@once", close: "@endonce", name: "once" },
+  { open: "@markdown", close: "@endmarkdown", name: "markdown" },
+  { open: "@component", close: "@endcomponent", name: "component" }
+], MALFORMED_DIRECTIVE_CHECKS = [
+  { pattern: /@if\s*[^(]/, message: "@if directive missing parentheses", suggestion: "Use @if(condition)" },
+  { pattern: /@foreach\s*[^(]/, message: "@foreach directive missing parentheses", suggestion: "Use @foreach(items as item)" },
+  { pattern: /@foreach\([^)]*\)\s*[^@\n<]/, message: "@foreach may have content on same line", suggestion: "Put content on new line after @foreach()" },
+  { pattern: /@include\s*[^(]/, message: "@include directive missing parentheses", suggestion: "Use @include('partial-name')" },
+  { pattern: /@extends\s*[^(]/, message: "@extends directive missing parentheses", suggestion: "Use @extends('layout-name') or @layout('layout-name')" },
+  { pattern: /@layout\s*[^(]/, message: "@layout directive missing parentheses", suggestion: "Use @layout('layout-name')" }
+], DANGEROUS_PATTERN_CHECKS = [
+  { pattern: /\{\{\s*constructor\s*\}\}/, message: "Attempting to access constructor property" },
+  { pattern: /\{\{\s*__proto__\s*\}\}/, message: "Attempting to access __proto__ property" },
+  { pattern: /\{\{\s*eval\s*\(/, message: "Attempting to use eval in expression" }
+];
+export function validateTemplate(template) {
+  const errors = [], warnings = [];
+  validateExpressionBrackets(template, errors);
+  validateDirectivePairs(template, errors, warnings);
+  validateDirectiveSyntax(template, warnings);
+  validateSecurityPatterns(template, errors);
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function validateExpressionBrackets(template, errors) {
+  const expressionOpens = (template.match(/\{\{/g) || []).length, expressionCloses = (template.match(/\}\}/g) || []).length;
+  if (expressionOpens !== expressionCloses)
+    errors.push({
+      type: "expression",
+      message: `Unclosed expression brackets: found ${expressionOpens} opening '{{' and ${expressionCloses} closing '}}'`,
+      suggestion: "Ensure every {{ has a matching }}"
+    });
+}
+function validateDirectivePairs(template, errors, warnings) {
+  for (const pair of DIRECTIVE_PAIRS) {
+    const openRegex = new RegExp(`${pair.open}(?:\\s|\\()`, "g"), closeRegex = new RegExp(pair.close, "g"), openCount = (template.match(openRegex) || []).length;
+    let closeCount = (template.match(closeRegex) || []).length;
+    if (pair.altClose) {
+      const altCloseRegex = new RegExp(pair.altClose, "g");
+      closeCount += (template.match(altCloseRegex) || []).length;
+    }
+    if (openCount > closeCount)
+      errors.push({
+        type: "directive",
+        message: `Unclosed @${pair.name} directive: found ${openCount} opening and ${closeCount} closing`,
+        suggestion: `Add ${openCount - closeCount} missing ${pair.close} tag(s)`
+      });
+    else if (closeCount > openCount)
+      warnings.push({
+        type: "directive",
+        message: `Extra ${pair.close} found: ${closeCount - openCount} more closing than opening`,
+        suggestion: `Check for orphaned ${pair.close} tags`
+      });
+  }
+}
+function validateDirectiveSyntax(template, warnings) {
+  for (const check of MALFORMED_DIRECTIVE_CHECKS)
+    if (check.pattern.test(template))
+      warnings.push({
+        type: "syntax",
+        message: check.message,
+        suggestion: check.suggestion
+      });
+}
+function validateSecurityPatterns(template, errors) {
+  for (const check of DANGEROUS_PATTERN_CHECKS)
+    if (check.pattern.test(template))
+      errors.push({
+        type: "expression",
+        message: `Security warning: ${check.message}`,
+        suggestion: "Remove dangerous code from template expressions"
+      });
+}
+export function getPositionInfo(template, position) {
+  const lines = template.slice(0, position).split(`
+`);
+  return {
+    line: lines.length,
+    column: lines[lines.length - 1].length + 1
+  };
+}
+export function validateDirective(directiveName, content, params) {
+  const errors = [];
+  switch (directiveName) {
+    case "if":
+    case "elseif":
+    case "unless":
+      if (params.length === 0)
+        errors.push({
+          type: "syntax",
+          message: `@${directiveName} requires a condition`,
+          suggestion: `Use @${directiveName}(condition)`
+        });
+      break;
+    case "foreach":
+      if (params.length === 0 || !params[0].includes(" as "))
+        errors.push({
+          type: "syntax",
+          message: '@foreach requires "items as item" syntax',
+          suggestion: "Use @foreach(items as item) or @foreach(items as key => value)"
+        });
+      break;
+    case "for":
+      if (params.length === 0)
+        errors.push({
+          type: "syntax",
+          message: "@for requires loop parameters",
+          suggestion: "Use @for(let i = 0; i < 10; i++)"
+        });
+      break;
+    case "switch":
+      if (params.length === 0)
+        errors.push({
+          type: "syntax",
+          message: "@switch requires an expression",
+          suggestion: "Use @switch(expression)"
+        });
+      break;
+    case "case":
+      if (params.length === 0)
+        errors.push({
+          type: "syntax",
+          message: "@case requires a value",
+          suggestion: "Use @case(value)"
+        });
+      break;
+    case "include":
+    case "extends":
+    case "component":
+      if (params.length === 0)
+        errors.push({
+          type: "syntax",
+          message: `@${directiveName} requires a path`,
+          suggestion: `Use @${directiveName}('path/to/template')`
+        });
+      break;
+  }
+  return errors;
+}
+export function hasDirectives(template) {
+  return /@[a-z]+/i.test(template) || /\{\{/.test(template);
+}
+export function extractDirectiveNames(template) {
+  const matches = template.matchAll(/@([a-z]+)/gi), names = new Set;
+  for (const match of matches) {
+    const name = match[1].toLowerCase();
+    if (!name.startsWith("end"))
+      names.add(name);
+  }
+  return Array.from(names);
+}

package/dist/variable-extractor.d.ts

@@ -0,0 +1,142 @@
+/**
+ * The runtime bindings the engine hands a `<script server>` block as function
+ * parameters, in the order the parameters are declared.
+ *
+ * This drives the `new Function` parameter list rather than sitting beside it,
+ * because the two must not drift: the value list below it is positional, so a
+ * name added in one place and not the other silently rebinds every argument
+ * after it.
+ *
+ * It is also the set a `from 'stx'` import must not redeclare. A server script
+ * writing the documented `import { defineProps } from 'stx'` was rewritten to
+ * `const { defineProps } = await import('stx')`, and that `const` shadows the
+ * parameter of the same name. The package's own `defineProps` reads
+ * `globalThis.__STX_CURRENT_PROPS__`, which nothing on the server path ever
+ * sets — so props came back `{}` and every component rendered empty.
+ *
+ * It went unnoticed because `stx` does not resolve inside this repo (the
+ * published package is `@stacksjs/stx`; the root `stx` is private), so the
+ * generated `await import('stx')` rejected and the shadowing binding was never
+ * created. The failure needed a real install to appear.
+ */
+export declare const STX_ENGINE_BINDING_NAMES: readonly ['module', 'exports', 'require', 'props', '$props', 'defineProps', 'withDefaults', 'defineClientPayload', 'state', 'derived', 'effect', 'batch', 'onMount', 'onDestroy', 'definePageMeta', 'useRoute', 'useRouter', 'useHead', 'useSeoMeta', 'setResponseStatus', 'setResponseHeader', 'notFound', 'ref', 'reactive', 'computed', 'watch', 'onMounted', 'onUnmounted', 'nextTick', 'defineEmits', 'defineExpose', 'defineSlots', 'provide', 'inject', 'useColorMode', 'useDark', 'useMediaQuery', 'useScrollLock', 'usePreferredDark', 'usePreferredLight', 'usePreferredReducedMotion', 'usePreferredContrast', 'window', 'document', 'console', 'confirm', 'alert', 'fetch', 'params'];
+/**
+ * Strip TypeScript-specific syntax to make it executable as JavaScript
+ *
+ * @param scriptContent - TypeScript/JavaScript code
+ * @returns JavaScript code with TypeScript syntax stripped
+ */
+export declare function stripTypeScript(scriptContent: string): string;
+/**
+ * Whether a script failure was a module that could not be found.
+ *
+ * Matched on the message because the failure arrives as a plain Error from the
+ * runtime's loader rather than a typed one, and the wording differs between
+ * Bun and Node.
+ */
+export declare function isModuleResolutionFailure(message: string): boolean;
+/**
+ * Whether a script failed because it named something that does not exist.
+ *
+ * The same category as a module that will not resolve, and worth the same
+ * unconditional warning for the same reason: it is never the legitimate case
+ * the silence exists for. A page that uses only client APIs fails here on
+ * `document` or `window`, which is expected and quiet - but those are the
+ * *only* names it fails on, and a script that trips over anything else has a
+ * bug in it.
+ *
+ * A missing binding is particularly cruel because optional chaining does not
+ * help. `foo?.bar` guards an undefined *property*; an undefined *identifier* is
+ * a ReferenceError before the chain is reached, so a script that carefully
+ * writes `someContext?.value` still throws and still takes every variable in
+ * the file down with it. A page then renders its empty-state branch and reads
+ * as a correct answer rather than as a failure, which is exactly the shape that
+ * is expensive to find.
+ */
+export declare function isMissingBindingFailure(message: string): boolean;
+/**
+ * Extract variables from script content and add them to context
+ *
+ * @param scriptContent - The JavaScript/TypeScript code from a <script> tag
+ * @param context - The context object to populate with extracted variables
+ * @param filePath - Path to the file (for error messages)
+ */
+export interface ExtractVariablesOptions {
+    /**
+     * Don't overwrite a context key that already has a value. Use this
+     * when extracting from a LAYOUT or PARTIAL `<script server>` so the
+     * child page's identifier wins — layouts can declare stubs/defaults
+     * (`const user = { avatarInitials: 'JD' }`) without clobbering the
+     * full object the page set on the same name.
+     *
+     * Off by default: page-level extraction (in render.ts) still
+     * overrides caller-supplied context values, matching pre-flag
+     * behaviour. Only the layout/partial extraction path in process.ts
+     * passes this flag on.
+     */
+    preserveExisting?: boolean;
+}
+export declare function extractVariables(scriptContent: string, context: Record<string, unknown>, filePath: string, options?: ExtractVariablesOptions): Promise<void>;
+/**
+ * Convert ES module syntax to CommonJS
+ *
+ * @param scriptContent - ES module style script content
+ * @returns CommonJS compatible script
+ */
+/**
+ * Whether an import statement is finished, or continues on the next line.
+ *
+ * Finished means the module specifier has been reached and its quotes are
+ * closed, with no unclosed brace left over. A side-effect import
+ * (`import './setup'`) is complete as soon as its string closes; a named
+ * import is not complete until both the brace list and the specifier are.
+ *
+ * Exported for the tests, because the failure it prevents is invisible from
+ * the outside: an unjoined import produces a syntax error in generated code,
+ * and the page then renders with every server variable undefined.
+ */
+export declare function isCompleteImport(statement: string): boolean;
+export declare function convertToCommonJS(scriptContent: string, filePath?: string): string;
+/**
+ * Parse variable declarations (including multi-line objects and arrays)
+ */
+/**
+ * Split `const name: Type = value` into its parts.
+ *
+ * The pattern this supports used to require the `=` to follow the name
+ * directly, so any TypeScript annotation made the declaration unparseable. That
+ * is not a small failure: an unparseable declaration throws out of
+ * `convertToCommonJS`, the whole server script falls back to static
+ * extraction, and the page renders with every variable undefined and no error.
+ * A single `const rows: any = await db...` was enough to blank a page.
+ *
+ * The annotation is erased at runtime, so it only has to be skipped. It is
+ * scanned rather than matched because it can contain almost anything: `=` in a
+ * generic default, braces in an object type, commas and angle brackets in a
+ * generic argument list.
+ *
+ * Returns null when the line is not a simple declaration, which leaves the
+ * destructuring and multi-line paths below to handle it as before.
+ */
+export declare function splitDeclaration(line: string): {
+    type: string;
+    name: string;
+    value: string;
+} | null;
+/**
+ * Extract script content from an HTML template
+ *
+ * @param template - The template string
+ * @returns Object with script content and template without script tags
+ */
+export declare function extractScriptFromTemplate(template: string): {
+    scriptContent: string;
+    templateWithoutScript: string;
+};
+/**
+ * Check if script content has any variables to extract
+ *
+ * @param scriptContent - The script content
+ * @returns Whether variables are present
+ */
+export declare function hasVariables(scriptContent: string): boolean;