@constela/compiler 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Constela Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,198 @@
+import { Program, ConstelaError } from '@constela/core';
+export { createUndefinedVarError } from '@constela/core';
+
+/**
+ * Analyze Pass - Static analysis for semantic validation
+ *
+ * This pass performs semantic analysis on the validated AST:
+ * - Collects state and action names
+ * - Validates state references
+ * - Validates action references
+ * - Validates variable scopes in each loops
+ * - Detects duplicate action names
+ */
+
+interface AnalysisContext {
+    stateNames: Set<string>;
+    actionNames: Set<string>;
+}
+interface AnalyzePassSuccess {
+    ok: true;
+    ast: Program;
+    context: AnalysisContext;
+}
+interface AnalyzePassFailure {
+    ok: false;
+    errors: ConstelaError[];
+}
+type AnalyzePassResult = AnalyzePassSuccess | AnalyzePassFailure;
+
+/**
+ * Performs static analysis on the validated AST
+ *
+ * - Collects state names
+ * - Collects action names
+ * - Validates state references
+ * - Validates action references
+ * - Validates variable scopes
+ *
+ * @param ast - Validated AST from validate pass
+ * @returns AnalyzePassResult
+ */
+declare function analyzePass(ast: Program): AnalyzePassResult;
+
+/**
+ * Transform Pass - AST to CompiledProgram transformation
+ *
+ * This pass transforms the validated and analyzed AST into a CompiledProgram
+ * that is optimized for runtime execution.
+ */
+
+interface CompiledProgram {
+    version: '1.0';
+    state: Record<string, {
+        type: string;
+        initial: unknown;
+    }>;
+    actions: Record<string, CompiledAction>;
+    view: CompiledNode;
+}
+interface CompiledAction {
+    name: string;
+    steps: CompiledActionStep[];
+}
+type CompiledActionStep = CompiledSetStep | CompiledUpdateStep | CompiledFetchStep;
+interface CompiledSetStep {
+    do: 'set';
+    target: string;
+    value: CompiledExpression;
+}
+interface CompiledUpdateStep {
+    do: 'update';
+    target: string;
+    operation: string;
+    value?: CompiledExpression;
+}
+interface CompiledFetchStep {
+    do: 'fetch';
+    url: CompiledExpression;
+    method?: string;
+    body?: CompiledExpression;
+    result?: string;
+    onSuccess?: CompiledActionStep[];
+    onError?: CompiledActionStep[];
+}
+type CompiledNode = CompiledElementNode | CompiledTextNode | CompiledIfNode | CompiledEachNode;
+interface CompiledElementNode {
+    kind: 'element';
+    tag: string;
+    props?: Record<string, CompiledExpression | CompiledEventHandler>;
+    children?: CompiledNode[];
+}
+interface CompiledTextNode {
+    kind: 'text';
+    value: CompiledExpression;
+}
+interface CompiledIfNode {
+    kind: 'if';
+    condition: CompiledExpression;
+    then: CompiledNode;
+    else?: CompiledNode;
+}
+interface CompiledEachNode {
+    kind: 'each';
+    items: CompiledExpression;
+    as: string;
+    index?: string;
+    key?: CompiledExpression;
+    body: CompiledNode;
+}
+type CompiledExpression = CompiledLitExpr | CompiledStateExpr | CompiledVarExpr | CompiledBinExpr | CompiledNotExpr;
+interface CompiledLitExpr {
+    expr: 'lit';
+    value: string | number | boolean | null | unknown[];
+}
+interface CompiledStateExpr {
+    expr: 'state';
+    name: string;
+}
+interface CompiledVarExpr {
+    expr: 'var';
+    name: string;
+    path?: string;
+}
+interface CompiledBinExpr {
+    expr: 'bin';
+    op: string;
+    left: CompiledExpression;
+    right: CompiledExpression;
+}
+interface CompiledNotExpr {
+    expr: 'not';
+    operand: CompiledExpression;
+}
+interface CompiledEventHandler {
+    event: string;
+    action: string;
+    payload?: CompiledExpression;
+}
+/**
+ * Transforms the validated and analyzed AST into a CompiledProgram
+ *
+ * @param ast - Validated AST from validate pass
+ * @param _context - Analysis context from analyze pass (unused in current implementation)
+ * @returns CompiledProgram
+ */
+declare function transformPass(ast: Program, _context: AnalysisContext): CompiledProgram;
+
+/**
+ * Main compile function for @constela/compiler
+ *
+ * This module provides the main compile function that orchestrates
+ * the three compilation passes: validate -> analyze -> transform.
+ */
+
+interface CompileSuccess {
+    ok: true;
+    program: CompiledProgram;
+}
+interface CompileFailure {
+    ok: false;
+    errors: ConstelaError[];
+}
+type CompileResult = CompileSuccess | CompileFailure;
+/**
+ * Compiles a Constela AST into a CompiledProgram
+ *
+ * Pipeline: validate -> analyze -> transform
+ *
+ * @param input - Raw AST input to compile
+ * @returns CompileResult with either compiled program or errors
+ */
+declare function compile(input: unknown): CompileResult;
+
+/**
+ * Validate Pass - Schema validation using @constela/core
+ *
+ * This pass validates the raw input against the Constela AST schema
+ * and performs basic semantic validation.
+ */
+
+interface ValidatePassSuccess {
+    ok: true;
+    ast: Program;
+}
+interface ValidatePassFailure {
+    ok: false;
+    error: ConstelaError;
+}
+type ValidatePassResult = ValidatePassSuccess | ValidatePassFailure;
+/**
+ * Validates the AST using @constela/core validateAst
+ *
+ * @param input - Raw input to validate
+ * @returns ValidatePassResult
+ */
+declare function validatePass(input: unknown): ValidatePassResult;
+
+export { type AnalysisContext, type AnalyzePassFailure, type AnalyzePassResult, type AnalyzePassSuccess, type CompileFailure, type CompileResult, type CompileSuccess, type CompiledAction, type CompiledActionStep, type CompiledEachNode, type CompiledElementNode, type CompiledEventHandler, type CompiledExpression, type CompiledIfNode, type CompiledNode, type CompiledProgram, type CompiledTextNode, type ValidatePassFailure, type ValidatePassResult, type ValidatePassSuccess, analyzePass, compile, transformPass, validatePass };

package/dist/index.js

@@ -0,0 +1,483 @@
+// src/passes/validate.ts
+import { validateAst } from "@constela/core";
+function validatePass(input) {
+  const result = validateAst(input);
+  if (result.ok) {
+    return {
+      ok: true,
+      ast: result.ast
+    };
+  }
+  return {
+    ok: false,
+    error: result.error
+  };
+}
+
+// src/passes/analyze.ts
+import {
+  createUndefinedStateError,
+  createUndefinedActionError,
+  createUndefinedVarError,
+  createDuplicateActionError,
+  isEventHandler
+} from "@constela/core";
+function buildPath(base, ...segments) {
+  return segments.reduce((p, s) => `${p}/${s}`, base);
+}
+function collectContext(ast) {
+  const stateNames = new Set(Object.keys(ast.state));
+  const actionNames = new Set(ast.actions.map((a) => a.name));
+  return { stateNames, actionNames };
+}
+function checkDuplicateActions(ast) {
+  const errors = [];
+  const seenNames = /* @__PURE__ */ new Set();
+  for (let i = 0; i < ast.actions.length; i++) {
+    const action = ast.actions[i];
+    if (action === void 0) continue;
+    if (seenNames.has(action.name)) {
+      errors.push(createDuplicateActionError(action.name, `/actions/${i}`));
+    }
+    seenNames.add(action.name);
+  }
+  return errors;
+}
+function validateExpression(expr, path, context, scope) {
+  const errors = [];
+  switch (expr.expr) {
+    case "state":
+      if (!context.stateNames.has(expr.name)) {
+        errors.push(createUndefinedStateError(expr.name, path));
+      }
+      break;
+    case "var":
+      if (!scope.has(expr.name)) {
+        errors.push(createUndefinedVarError(expr.name, path));
+      }
+      break;
+    case "bin":
+      errors.push(...validateExpression(expr.left, buildPath(path, "left"), context, scope));
+      errors.push(...validateExpression(expr.right, buildPath(path, "right"), context, scope));
+      break;
+    case "not":
+      errors.push(...validateExpression(expr.operand, buildPath(path, "operand"), context, scope));
+      break;
+    case "lit":
+      break;
+  }
+  return errors;
+}
+function validateActionStep(step, path, context) {
+  const errors = [];
+  switch (step.do) {
+    case "set":
+      if (!context.stateNames.has(step.target)) {
+        errors.push(createUndefinedStateError(step.target, buildPath(path, "target")));
+      }
+      errors.push(
+        ...validateExpressionStateOnly(step.value, buildPath(path, "value"), context)
+      );
+      break;
+    case "update":
+      if (!context.stateNames.has(step.target)) {
+        errors.push(createUndefinedStateError(step.target, buildPath(path, "target")));
+      }
+      if (step.value) {
+        errors.push(
+          ...validateExpressionStateOnly(step.value, buildPath(path, "value"), context)
+        );
+      }
+      break;
+    case "fetch":
+      errors.push(
+        ...validateExpressionStateOnly(step.url, buildPath(path, "url"), context)
+      );
+      if (step.body) {
+        errors.push(
+          ...validateExpressionStateOnly(step.body, buildPath(path, "body"), context)
+        );
+      }
+      if (step.onSuccess) {
+        for (let i = 0; i < step.onSuccess.length; i++) {
+          const successStep = step.onSuccess[i];
+          if (successStep === void 0) continue;
+          errors.push(
+            ...validateActionStep(successStep, buildPath(path, "onSuccess", i), context)
+          );
+        }
+      }
+      if (step.onError) {
+        for (let i = 0; i < step.onError.length; i++) {
+          const errorStep = step.onError[i];
+          if (errorStep === void 0) continue;
+          errors.push(
+            ...validateActionStep(errorStep, buildPath(path, "onError", i), context)
+          );
+        }
+      }
+      break;
+  }
+  return errors;
+}
+function validateExpressionStateOnly(expr, path, context) {
+  const errors = [];
+  switch (expr.expr) {
+    case "state":
+      if (!context.stateNames.has(expr.name)) {
+        errors.push(createUndefinedStateError(expr.name, path));
+      }
+      break;
+    case "var":
+      break;
+    case "bin":
+      errors.push(...validateExpressionStateOnly(expr.left, buildPath(path, "left"), context));
+      errors.push(...validateExpressionStateOnly(expr.right, buildPath(path, "right"), context));
+      break;
+    case "not":
+      errors.push(
+        ...validateExpressionStateOnly(expr.operand, buildPath(path, "operand"), context)
+      );
+      break;
+    case "lit":
+      break;
+  }
+  return errors;
+}
+function validateExpressionInEventPayload(expr, path, context, scope) {
+  const errors = [];
+  switch (expr.expr) {
+    case "state":
+      if (!context.stateNames.has(expr.name)) {
+        errors.push(createUndefinedStateError(expr.name, path));
+      }
+      break;
+    case "var":
+      break;
+    case "bin":
+      errors.push(
+        ...validateExpressionInEventPayload(expr.left, buildPath(path, "left"), context, scope)
+      );
+      errors.push(
+        ...validateExpressionInEventPayload(expr.right, buildPath(path, "right"), context, scope)
+      );
+      break;
+    case "not":
+      errors.push(
+        ...validateExpressionInEventPayload(
+          expr.operand,
+          buildPath(path, "operand"),
+          context,
+          scope
+        )
+      );
+      break;
+    case "lit":
+      break;
+  }
+  return errors;
+}
+function validateViewNode(node, path, context, scope) {
+  const errors = [];
+  switch (node.kind) {
+    case "element":
+      if (node.props) {
+        for (const [propName, propValue] of Object.entries(node.props)) {
+          const propPath = buildPath(path, "props", propName);
+          if (isEventHandler(propValue)) {
+            if (!context.actionNames.has(propValue.action)) {
+              errors.push(createUndefinedActionError(propValue.action, propPath));
+            }
+            if (propValue.payload) {
+              errors.push(
+                ...validateExpressionInEventPayload(
+                  propValue.payload,
+                  buildPath(propPath, "payload"),
+                  context,
+                  scope
+                )
+              );
+            }
+          } else {
+            errors.push(...validateExpression(propValue, propPath, context, scope));
+          }
+        }
+      }
+      if (node.children) {
+        for (let i = 0; i < node.children.length; i++) {
+          const child = node.children[i];
+          if (child === void 0) continue;
+          errors.push(
+            ...validateViewNode(child, buildPath(path, "children", i), context, scope)
+          );
+        }
+      }
+      break;
+    case "text":
+      errors.push(...validateExpression(node.value, buildPath(path, "value"), context, scope));
+      break;
+    case "if":
+      errors.push(
+        ...validateExpression(node.condition, buildPath(path, "condition"), context, scope)
+      );
+      errors.push(...validateViewNode(node.then, buildPath(path, "then"), context, scope));
+      if (node.else) {
+        errors.push(...validateViewNode(node.else, buildPath(path, "else"), context, scope));
+      }
+      break;
+    case "each":
+      errors.push(...validateExpression(node.items, buildPath(path, "items"), context, scope));
+      const bodyScope = new Set(scope);
+      bodyScope.add(node.as);
+      if (node.index) {
+        bodyScope.add(node.index);
+      }
+      if (node.key) {
+        errors.push(...validateExpression(node.key, buildPath(path, "key"), context, bodyScope));
+      }
+      errors.push(...validateViewNode(node.body, buildPath(path, "body"), context, bodyScope));
+      break;
+  }
+  return errors;
+}
+function validateActions(ast, context) {
+  const errors = [];
+  for (let i = 0; i < ast.actions.length; i++) {
+    const action = ast.actions[i];
+    if (action === void 0) continue;
+    for (let j = 0; j < action.steps.length; j++) {
+      const step = action.steps[j];
+      if (step === void 0) continue;
+      errors.push(
+        ...validateActionStep(step, buildPath("", "actions", i, "steps", j), context)
+      );
+    }
+  }
+  return errors;
+}
+function analyzePass(ast) {
+  const context = collectContext(ast);
+  const errors = [];
+  errors.push(...checkDuplicateActions(ast));
+  errors.push(...validateActions(ast, context));
+  errors.push(...validateViewNode(ast.view, "/view", context, /* @__PURE__ */ new Set()));
+  if (errors.length > 0) {
+    return {
+      ok: false,
+      errors
+    };
+  }
+  return {
+    ok: true,
+    ast,
+    context
+  };
+}
+
+// src/passes/transform.ts
+import { isEventHandler as isEventHandler2 } from "@constela/core";
+function transformExpression(expr) {
+  switch (expr.expr) {
+    case "lit":
+      return {
+        expr: "lit",
+        value: expr.value
+      };
+    case "state":
+      return {
+        expr: "state",
+        name: expr.name
+      };
+    case "var": {
+      const varExpr = {
+        expr: "var",
+        name: expr.name
+      };
+      if (expr.path) {
+        varExpr.path = expr.path;
+      }
+      return varExpr;
+    }
+    case "bin":
+      return {
+        expr: "bin",
+        op: expr.op,
+        left: transformExpression(expr.left),
+        right: transformExpression(expr.right)
+      };
+    case "not":
+      return {
+        expr: "not",
+        operand: transformExpression(expr.operand)
+      };
+  }
+}
+function transformEventHandler(handler) {
+  const result = {
+    event: handler.event,
+    action: handler.action
+  };
+  if (handler.payload) {
+    result.payload = transformExpression(handler.payload);
+  }
+  return result;
+}
+function transformActionStep(step) {
+  switch (step.do) {
+    case "set":
+      return {
+        do: "set",
+        target: step.target,
+        value: transformExpression(step.value)
+      };
+    case "update": {
+      const updateStep = {
+        do: "update",
+        target: step.target,
+        operation: step.operation
+      };
+      if (step.value) {
+        updateStep.value = transformExpression(step.value);
+      }
+      return updateStep;
+    }
+    case "fetch": {
+      const fetchStep = {
+        do: "fetch",
+        url: transformExpression(step.url)
+      };
+      if (step.method) {
+        fetchStep.method = step.method;
+      }
+      if (step.body) {
+        fetchStep.body = transformExpression(step.body);
+      }
+      if (step.result) {
+        fetchStep.result = step.result;
+      }
+      if (step.onSuccess) {
+        fetchStep.onSuccess = step.onSuccess.map(transformActionStep);
+      }
+      if (step.onError) {
+        fetchStep.onError = step.onError.map(transformActionStep);
+      }
+      return fetchStep;
+    }
+  }
+}
+function transformViewNode(node) {
+  switch (node.kind) {
+    case "element": {
+      const compiledElement = {
+        kind: "element",
+        tag: node.tag
+      };
+      if (node.props) {
+        compiledElement.props = {};
+        for (const [propName, propValue] of Object.entries(node.props)) {
+          if (isEventHandler2(propValue)) {
+            compiledElement.props[propName] = transformEventHandler(propValue);
+          } else {
+            compiledElement.props[propName] = transformExpression(propValue);
+          }
+        }
+      }
+      if (node.children && node.children.length > 0) {
+        compiledElement.children = node.children.map(transformViewNode);
+      }
+      return compiledElement;
+    }
+    case "text":
+      return {
+        kind: "text",
+        value: transformExpression(node.value)
+      };
+    case "if": {
+      const compiledIf = {
+        kind: "if",
+        condition: transformExpression(node.condition),
+        then: transformViewNode(node.then)
+      };
+      if (node.else) {
+        compiledIf.else = transformViewNode(node.else);
+      }
+      return compiledIf;
+    }
+    case "each": {
+      const compiledEach = {
+        kind: "each",
+        items: transformExpression(node.items),
+        as: node.as,
+        body: transformViewNode(node.body)
+      };
+      if (node.index) {
+        compiledEach.index = node.index;
+      }
+      if (node.key) {
+        compiledEach.key = transformExpression(node.key);
+      }
+      return compiledEach;
+    }
+  }
+}
+function transformState(state) {
+  const compiledState = {};
+  for (const [name, field] of Object.entries(state)) {
+    compiledState[name] = {
+      type: field.type,
+      initial: field.initial
+    };
+  }
+  return compiledState;
+}
+function transformActions(actions) {
+  const compiledActions = {};
+  for (const action of actions) {
+    compiledActions[action.name] = {
+      name: action.name,
+      steps: action.steps.map(transformActionStep)
+    };
+  }
+  return compiledActions;
+}
+function transformPass(ast, _context) {
+  return {
+    version: "1.0",
+    state: transformState(ast.state),
+    actions: transformActions(ast.actions),
+    view: transformViewNode(ast.view)
+  };
+}
+
+// src/compile.ts
+function compile(input) {
+  const validateResult = validatePass(input);
+  if (!validateResult.ok) {
+    return {
+      ok: false,
+      errors: [validateResult.error]
+    };
+  }
+  const analyzeResult = analyzePass(validateResult.ast);
+  if (!analyzeResult.ok) {
+    return {
+      ok: false,
+      errors: analyzeResult.errors
+    };
+  }
+  const program = transformPass(analyzeResult.ast, analyzeResult.context);
+  return {
+    ok: true,
+    program
+  };
+}
+
+// src/index.ts
+import { createUndefinedVarError as createUndefinedVarError2 } from "@constela/core";
+export {
+  analyzePass,
+  compile,
+  createUndefinedVarError2 as createUndefinedVarError,
+  transformPass,
+  validatePass
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@constela/compiler",
+  "version": "0.1.0",
+  "description": "Compiler for Constela UI framework - AST to Program transformation",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@constela/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist"
+  }
+}