@velox0/cerver 0.1.0

package/lib/ir/transform.js

@@ -0,0 +1,335 @@
+"use strict";
+
+const IR = require("./types");
+
+/**
+ * Transform a validated AST into an IR route descriptor.
+ *
+ * @param {object} ast - ESTree AST (validated)
+ * @param {string} urlPath - The route path (e.g. "/art/:key")
+ * @returns {IRRoute[]} — one IRRoute per exported handler (GET, POST)
+ */
+function transformFile(ast, urlPath) {
+  const routes = [];
+
+  /* Extract dynamic segment names from the URL pattern */
+  const params = [];
+  const paramRegex = /:([^/]+)/g;
+  let match;
+  while ((match = paramRegex.exec(urlPath)) !== null) {
+    params.push(match[1]);
+  }
+
+  for (const node of ast.body) {
+    if (
+      node.type === "ExportNamedDeclaration" &&
+      node.declaration &&
+      node.declaration.type === "FunctionDeclaration"
+    ) {
+      const funcDecl = node.declaration;
+      const method = funcDecl.id.name; /* "GET" or "POST" */
+
+      /* Get the parameter names (req, res) */
+      const reqName =
+        funcDecl.params[0] && funcDecl.params[0].type === "Identifier"
+          ? funcDecl.params[0].name
+          : "req";
+      const resName =
+        funcDecl.params[1] && funcDecl.params[1].type === "Identifier"
+          ? funcDecl.params[1].name
+          : "res";
+
+      /* Transform the function body */
+      const ctx = { reqName, resName };
+      const { variables, body } = transformBlock(funcDecl.body, ctx);
+
+      const handler = IR.IRHandler(variables, body);
+      routes.push(IR.IRRoute(method, urlPath, params, handler));
+    }
+  }
+
+  return routes;
+}
+
+/**
+ * Transform a block statement into IR variables and statements.
+ */
+function transformBlock(blockNode, ctx) {
+  const variables = [];
+  const body = [];
+
+  for (const stmt of blockNode.body) {
+    const result = transformStatement(stmt, ctx);
+    if (result) {
+      if (result.type === "Variable") {
+        variables.push(result);
+      } else {
+        body.push(result);
+      }
+    }
+  }
+
+  return { variables, body };
+}
+
+/**
+ * Transform a single statement.
+ */
+function transformStatement(node, ctx) {
+  switch (node.type) {
+    case "ReturnStatement":
+      return transformReturn(node, ctx);
+
+    case "IfStatement":
+      return transformIf(node, ctx);
+
+    case "VariableDeclaration":
+      return transformVariableDecl(node, ctx);
+
+    case "ExpressionStatement":
+      /* Likely a standalone res.text() call or similar */
+      return transformExpression(node.expression, ctx);
+
+    default:
+      return null;
+  }
+}
+
+/**
+ * Transform a return statement.
+ *
+ * Expected forms:
+ *   return res.text(200, "hello")
+ *   return res.json(200, '{"ok": true}')
+ *   return res.html(200, "<h1>hi</h1>")
+ */
+function transformReturn(node, ctx) {
+  if (!node.argument) {
+    return IR.IRReturn("text", 200, IR.IRStringLiteral(""));
+  }
+
+  const arg = node.argument;
+
+  /* res.text(status, body) */
+  if (
+    arg.type === "CallExpression" &&
+    arg.callee.type === "MemberExpression" &&
+    arg.callee.object.type === "Identifier" &&
+    arg.callee.object.name === ctx.resName
+  ) {
+    const method = arg.callee.property.name; /* "text", "json", "html" */
+    const responseType = ["text", "json", "html"].includes(method)
+      ? method
+      : "text";
+
+    const status =
+      arg.arguments[0] && arg.arguments[0].type === "Literal"
+        ? arg.arguments[0].value
+        : 200;
+
+    const bodyExpr = arg.arguments[1]
+      ? transformExpression(arg.arguments[1], ctx)
+      : IR.IRStringLiteral("");
+
+    return IR.IRReturn(responseType, status, bodyExpr);
+  }
+
+  /* Plain expression return — treat as text */
+  return IR.IRReturn(
+    "text",
+    200,
+    transformExpression(arg, ctx)
+  );
+}
+
+/**
+ * Transform an if statement.
+ */
+function transformIf(node, ctx) {
+  const condition = transformExpression(node.test, ctx);
+
+  const thenBlock = node.consequent.type === "BlockStatement"
+    ? transformBlock(node.consequent, ctx)
+    : { variables: [], body: [transformStatement(node.consequent, ctx)].filter(Boolean) };
+
+  let elseBody = null;
+  if (node.alternate) {
+    if (node.alternate.type === "IfStatement") {
+      /* else if → nested If */
+      elseBody = [transformStatement(node.alternate, ctx)];
+    } else if (node.alternate.type === "BlockStatement") {
+      const elseBlock = transformBlock(node.alternate, ctx);
+      elseBody = elseBlock.body;
+    } else {
+      elseBody = [transformStatement(node.alternate, ctx)].filter(Boolean);
+    }
+  }
+
+  return IR.IRIf(condition, thenBlock.body, elseBody);
+}
+
+/**
+ * Transform a variable declaration.
+ */
+function transformVariableDecl(node, ctx) {
+  /* For simplicity, handle the first declarator */
+  const decl = node.declarations[0];
+  if (!decl) return null;
+
+  const name = decl.id.name;
+  const initExpr = decl.init
+    ? transformExpression(decl.init, ctx)
+    : IR.IRStringLiteral("");
+
+  /* Infer type */
+  let valueType = "string";
+  if (initExpr.type === "NumberLiteral") {
+    valueType = "number";
+  }
+
+  return IR.IRVariable(name, valueType, initExpr);
+}
+
+/**
+ * Transform an expression into an IR expression node.
+ */
+function transformExpression(node, ctx) {
+  switch (node.type) {
+    case "Literal":
+      if (typeof node.value === "number") {
+        return IR.IRNumberLiteral(node.value);
+      }
+      return IR.IRStringLiteral(String(node.value || ""));
+
+    case "Identifier":
+      return IR.IRIdentifier(node.name);
+
+    case "BinaryExpression":
+      return IR.IRComparison(
+        node.operator,
+        transformExpression(node.left, ctx),
+        transformExpression(node.right, ctx)
+      );
+
+    case "LogicalExpression":
+      return IR.IRLogical(
+        node.operator,
+        transformExpression(node.left, ctx),
+        transformExpression(node.right, ctx)
+      );
+
+    case "UnaryExpression":
+      return IR.IRUnary(
+        node.operator,
+        transformExpression(node.argument, ctx)
+      );
+
+    case "ConditionalExpression":
+      /* a ? b : c → IR.IRIf as expression — simplify to if/else for now */
+      return IR.IRComparison(
+        "?:",
+        transformExpression(node.test, ctx),
+        transformExpression(node.consequent, ctx)
+      );
+
+    case "MemberExpression":
+      return transformMemberExpr(node, ctx);
+
+    case "CallExpression":
+      return transformCallExpr(node, ctx);
+
+    case "TemplateLiteral":
+      return transformTemplateLiteral(node, ctx);
+
+    case "AssignmentExpression":
+      /* Treat as a variable update — just return the right side for now */
+      return transformExpression(node.right, ctx);
+
+    default:
+      return IR.IRStringLiteral("");
+  }
+}
+
+/**
+ * Transform member expressions.
+ *
+ * Handles:
+ *   req.params.key  → IRParamAccess("key")
+ *   req.query.x     → IRQueryAccess("x")
+ *   req.headers.x   → IRHeaderAccess("x")
+ */
+function transformMemberExpr(node, ctx) {
+  /* req.params.key or req.query.key */
+  if (
+    node.object.type === "MemberExpression" &&
+    node.object.object.type === "Identifier" &&
+    node.object.object.name === ctx.reqName
+  ) {
+    const group = node.object.property.name || node.object.property.value;
+    const key = node.property.name || node.property.value;
+
+    if (group === "params") return IR.IRParamAccess(key);
+    if (group === "query") return IR.IRQueryAccess(key);
+    if (group === "headers") return IR.IRHeaderAccess(key);
+  }
+
+  /* req.method, req.path */
+  if (
+    node.object.type === "Identifier" &&
+    node.object.name === ctx.reqName
+  ) {
+    const prop = node.property.name || node.property.value;
+    if (prop === "method") return IR.IRIdentifier("req->method");
+    if (prop === "path") return IR.IRIdentifier("req->path");
+  }
+
+  return IR.IRStringLiteral("");
+}
+
+/**
+ * Transform call expressions.
+ */
+function transformCallExpr(node, ctx) {
+  /* res.text(status, body), res.json(...), res.html(...) */
+  if (
+    node.callee.type === "MemberExpression" &&
+    node.callee.object.type === "Identifier" &&
+    node.callee.object.name === ctx.resName
+  ) {
+    const method = node.callee.property.name;
+    const args = node.arguments.map((a) => transformExpression(a, ctx));
+    return IR.IRCall("res", method, args);
+  }
+
+  /* String methods like str.toLowerCase(), includes() etc. — return as-is */
+  if (node.callee.type === "MemberExpression") {
+    const obj = transformExpression(node.callee.object, ctx);
+    const method = node.callee.property.name;
+    const args = node.arguments.map((a) => transformExpression(a, ctx));
+    return IR.IRCall(obj, method, args);
+  }
+
+  return IR.IRStringLiteral("");
+}
+
+/**
+ * Transform template literals into concatenation.
+ */
+function transformTemplateLiteral(node, ctx) {
+  const parts = [];
+
+  for (let i = 0; i < node.quasis.length; i++) {
+    const quasi = node.quasis[i];
+    if (quasi.value.cooked) {
+      parts.push(IR.IRStringLiteral(quasi.value.cooked));
+    }
+    if (i < node.expressions.length) {
+      parts.push(transformExpression(node.expressions[i], ctx));
+    }
+  }
+
+  if (parts.length === 1) return parts[0];
+  return IR.IRConcat(parts);
+}
+
+module.exports = { transformFile };

package/lib/ir/types.js

@@ -0,0 +1,204 @@
+"use strict";
+
+/**
+ * IR type definitions for the cerver compiler.
+ *
+ * These are plain object constructors for the intermediate representation
+ * that sits between the AST and C code generation.
+ */
+
+/**
+ * A complete route definition.
+ */
+function IRRoute(method, urlPath, params, handler) {
+  return {
+    type: "Route",
+    method,     /* "GET" | "POST" */
+    urlPath,    /* "/item/:id" */
+    params,     /* ["id"] — extracted from dynamic segments */
+    handler,    /* IRHandler */
+  };
+}
+
+/**
+ * A route handler function body.
+ */
+function IRHandler(variables, body) {
+  return {
+    type: "Handler",
+    variables,  /* IRVariable[] */
+    body,       /* IRStatement[] */
+  };
+}
+
+/**
+ * A local variable declaration.
+ */
+function IRVariable(name, valueType, initExpr) {
+  return {
+    type: "Variable",
+    name,       /* C-safe variable name */
+    valueType,  /* "string" | "number" */
+    initExpr,   /* IRExpression — the initializer */
+  };
+}
+
+/**
+ * An if/else statement.
+ */
+function IRIf(condition, thenBody, elseBody) {
+  return {
+    type: "If",
+    condition,  /* IRExpression */
+    thenBody,   /* IRStatement[] */
+    elseBody,   /* IRStatement[] | null */
+  };
+}
+
+/**
+ * A return statement that sends an HTTP response.
+ */
+function IRReturn(responseType, status, value) {
+  return {
+    type: "Return",
+    responseType, /* "text" | "json" | "html" */
+    status,       /* number */
+    value,        /* IRExpression — the response body */
+  };
+}
+
+/**
+ * A string literal.
+ */
+function IRStringLiteral(value) {
+  return {
+    type: "StringLiteral",
+    value,
+  };
+}
+
+/**
+ * A number literal.
+ */
+function IRNumberLiteral(value) {
+  return {
+    type: "NumberLiteral",
+    value,
+  };
+}
+
+/**
+ * A comparison expression.
+ */
+function IRComparison(operator, left, right) {
+  return {
+    type: "Comparison",
+    operator, /* "==" | "!=" | "===" | "!==" */
+    left,     /* IRExpression */
+    right,    /* IRExpression */
+  };
+}
+
+/**
+ * A logical expression (&&, ||).
+ */
+function IRLogical(operator, left, right) {
+  return {
+    type: "Logical",
+    operator, /* "&&" | "||" */
+    left,
+    right,
+  };
+}
+
+/**
+ * A unary expression (!, -).
+ */
+function IRUnary(operator, argument) {
+  return {
+    type: "Unary",
+    operator,
+    argument,
+  };
+}
+
+/**
+ * Access to a request parameter: req.params.key
+ */
+function IRParamAccess(paramName) {
+  return {
+    type: "ParamAccess",
+    paramName,
+  };
+}
+
+/**
+ * Access to a query parameter: req.query.key
+ */
+function IRQueryAccess(queryName) {
+  return {
+    type: "QueryAccess",
+    queryName,
+  };
+}
+
+/**
+ * Access to a request header: req.headers["user-agent"]
+ */
+function IRHeaderAccess(headerName) {
+  return {
+    type: "HeaderAccess",
+    headerName,
+  };
+}
+
+/**
+ * A variable reference.
+ */
+function IRIdentifier(name) {
+  return {
+    type: "Identifier",
+    name,
+  };
+}
+
+/**
+ * A template literal (string interpolation).
+ */
+function IRConcat(parts) {
+  return {
+    type: "Concat",
+    parts, /* IRExpression[] — mix of literals and expressions */
+  };
+}
+
+/**
+ * A function call expression (for res.text, res.json, etc.)
+ */
+function IRCall(object, method, args) {
+  return {
+    type: "Call",
+    object,
+    method,
+    args,
+  };
+}
+
+module.exports = {
+  IRRoute,
+  IRHandler,
+  IRVariable,
+  IRIf,
+  IRReturn,
+  IRStringLiteral,
+  IRNumberLiteral,
+  IRComparison,
+  IRLogical,
+  IRUnary,
+  IRParamAccess,
+  IRQueryAccess,
+  IRHeaderAccess,
+  IRIdentifier,
+  IRConcat,
+  IRCall,
+};

package/lib/parser/discover.js

@@ -0,0 +1,74 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * Discover route files under app/routes/ and map them to URL paths.
+ *
+ * File-based routing convention:
+ *   app/routes/index.js      → /
+ *   app/routes/page.js       → /page
+ *   app/routes/group/item.js → /group/item
+ *   app/routes/item/[id].js  → /item/:id
+ *
+ * @param {string} routesDir - Absolute path to app/routes/
+ * @returns {Array<{ filePath: string, urlPath: string }>}
+ */
+function discoverRoutes(routesDir) {
+  const routes = [];
+
+  if (!fs.existsSync(routesDir)) {
+    return routes;
+  }
+
+  function walk(dir, prefix) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        walk(fullPath, prefix + "/" + entry.name);
+        continue;
+      }
+
+      if (!entry.name.endsWith(".js")) continue;
+
+      /* Build the URL path from the file path */
+      let urlPath;
+      const basename = entry.name.replace(/\.js$/, "");
+
+      if (basename === "index") {
+        urlPath = prefix || "/";
+      } else {
+        urlPath = prefix + "/" + basename;
+      }
+
+      /* Convert [param] to :param for dynamic segments */
+      urlPath = urlPath.replace(/\[([^\]]+)\]/g, ":$1");
+
+      /* Normalize double slashes */
+      urlPath = urlPath.replace(/\/+/g, "/");
+
+      routes.push({
+        filePath: fullPath,
+        urlPath,
+      });
+    }
+  }
+
+  walk(routesDir, "");
+
+  /* Sort: static routes before dynamic ones for predictable matching */
+  routes.sort((a, b) => {
+    const aDynamic = a.urlPath.includes(":");
+    const bDynamic = b.urlPath.includes(":");
+    if (aDynamic !== bDynamic) return aDynamic ? 1 : -1;
+    return a.urlPath.localeCompare(b.urlPath);
+  });
+
+  return routes;
+}
+
+module.exports = { discoverRoutes };

package/lib/parser/parse.js

@@ -0,0 +1,50 @@
+"use strict";
+
+const acorn = require("acorn");
+const fs = require("fs");
+
+/**
+ * Parse a JavaScript file into an ESTree AST using Acorn.
+ *
+ * @param {string} filePath - Absolute path to the .js file
+ * @returns {{ ast: object, source: string }}
+ */
+function parseFile(filePath) {
+  const source = fs.readFileSync(filePath, "utf8");
+
+  try {
+    const ast = acorn.parse(source, {
+      ecmaVersion: 2020,
+      sourceType: "module",
+      locations: true, /* line/column info for error reporting */
+    });
+
+    return { ast, source };
+  } catch (err) {
+    const loc = err.loc
+      ? `${filePath}:${err.loc.line}:${err.loc.column}`
+      : filePath;
+    throw new Error(`cerver: parse error at ${loc} — ${err.message}`);
+  }
+}
+
+/**
+ * Parse a source string directly (for testing / config parsing).
+ */
+function parseSource(source, filename) {
+  try {
+    const ast = acorn.parse(source, {
+      ecmaVersion: 2020,
+      sourceType: "module",
+      locations: true,
+    });
+    return { ast, source };
+  } catch (err) {
+    const loc = err.loc
+      ? `${filename || "<source>"}:${err.loc.line}:${err.loc.column}`
+      : filename || "<source>";
+    throw new Error(`cerver: parse error at ${loc} — ${err.message}`);
+  }
+}
+
+module.exports = { parseFile, parseSource };