bonescript-compiler 0.2.0

package/src/emit_extras.ts

@@ -0,0 +1,240 @@
+/**
+ * BoneScript Extras Emitter
+ * Handles features that don't fit cleanly into the main emitters:
+ * - Derived fields (computed columns / virtual getters)
+ * - Channel filter expressions
+ * - Flow compensation runtime
+ */
+
+import * as IR from "./ir";
+import * as AST from "./ast";
+
+function toSnakeCase(s: string): string {
+  return s.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+}
+
+// ─── Derived Field Emission ──────────────────────────────────────────────────
+// Derived fields become PostgreSQL generated columns (when expression supports it)
+// or TypeScript getters in the model class.
+
+export function emitDerivedFields(entity: AST.EntityDeclNode): string {
+  if (entity.derived.length === 0) return "";
+  const lines: string[] = [];
+  lines.push(`// Derived fields for ${entity.name}`);
+  lines.push(`export const ${entity.name.toUpperCase()}_DERIVED = {`);
+  for (const d of entity.derived) {
+    lines.push(`  ${d.name}: (entity: any): unknown => {`);
+    lines.push(`    // ${serializeExpr(d.expr)}`);
+    lines.push(`    return ${jsExpr(d.expr)};`);
+    lines.push(`  },`);
+  }
+  lines.push(`};`);
+  return lines.join("\n");
+}
+
+function serializeExpr(e: AST.ExprNode): string {
+  switch (e.kind) {
+    case "Literal":
+      if (e.type === "string") return `"${e.value}"`;
+      return String(e.value);
+    case "FieldRef": return e.path.join(".");
+    case "BinaryExpr": return `${serializeExpr(e.left)} ${e.op} ${serializeExpr(e.right)}`;
+    case "UnaryExpr": return `${e.op}${serializeExpr(e.operand)}`;
+    case "CallExpr": return `${e.name}(${e.args.map(serializeExpr).join(", ")})`;
+    case "TernaryExpr": return `${serializeExpr(e.condition)} ? ${serializeExpr(e.consequent)} : ${serializeExpr(e.alternate)}`;
+  }
+}
+
+function jsExpr(e: AST.ExprNode): string {
+  switch (e.kind) {
+    case "Literal":
+      if (e.type === "string") return JSON.stringify(e.value);
+      if (e.type === "none") return "null";
+      return String(e.value);
+    case "FieldRef":
+      return `entity.${e.path.join(".")}`;
+    case "BinaryExpr": {
+      const op = e.op === "and" ? "&&" : e.op === "or" ? "||" : e.op === "==" ? "===" : e.op === "!=" ? "!==" : e.op;
+      return `(${jsExpr(e.left)} ${op} ${jsExpr(e.right)})`;
+    }
+    case "UnaryExpr":
+      return `(${e.op === "not" ? "!" : e.op}${jsExpr(e.operand)})`;
+    case "CallExpr":
+      if (e.name === "now") return "Date.now()";
+      return `${e.name}(${e.args.map(jsExpr).join(", ")})`;
+    case "TernaryExpr":
+      return `(${jsExpr(e.condition)} ? ${jsExpr(e.consequent)} : ${jsExpr(e.alternate)})`;
+  }
+}
+
+// ─── Channel Filter Emission ─────────────────────────────────────────────────
+// Channels with filter expressions get a TypeScript predicate function attached
+// to the WebSocket subscription logic.
+
+export function emitChannelFilters(channels: AST.ChannelDeclNode[]): string {
+  const filtered = channels.filter(c => c.filter);
+  if (filtered.length === 0) return "";
+
+  const lines: string[] = [];
+  lines.push(`// Generated channel filter predicates`);
+  lines.push(`// Each filter is a deterministic function: (event, participant) -> bool`);
+  lines.push(``);
+  lines.push(`export const CHANNEL_FILTERS: Record<string, (event: any, participant: any) => boolean> = {`);
+  for (const ch of filtered) {
+    lines.push(`  "${ch.name}": (event, participant) => {`);
+    lines.push(`    // Filter expression: ${ch.filter ? serializeExpr(ch.filter) : "true"}`);
+    lines.push(`    return ${ch.filter ? channelFilterExpr(ch.filter) : "true"};`);
+    lines.push(`  },`);
+  }
+  lines.push(`};`);
+  lines.push(``);
+  lines.push(`export function shouldDeliver(channel: string, event: any, participant: any): boolean {`);
+  lines.push(`  const filter = CHANNEL_FILTERS[channel];`);
+  lines.push(`  return filter ? filter(event, participant) : true;`);
+  lines.push(`}`);
+
+  return lines.join("\n");
+}
+
+function channelFilterExpr(e: AST.ExprNode): string {
+  // Channel filters reference 'event' and 'participant' as implicit names
+  switch (e.kind) {
+    case "Literal":
+      if (e.type === "string") return JSON.stringify(e.value);
+      if (e.type === "none") return "null";
+      return String(e.value);
+    case "FieldRef": {
+      // Resolve event.* and participant.* explicitly
+      if (e.path[0] === "event" || e.path[0] === "participant") {
+        return e.path.join(".");
+      }
+      return `event.${e.path.join(".")}`;
+    }
+    case "BinaryExpr": {
+      const op = e.op === "and" ? "&&" : e.op === "or" ? "||" : e.op === "==" ? "===" : e.op === "!=" ? "!==" : e.op;
+      return `(${channelFilterExpr(e.left)} ${op} ${channelFilterExpr(e.right)})`;
+    }
+    case "UnaryExpr":
+      return `(${e.op === "not" ? "!" : e.op}${channelFilterExpr(e.operand)})`;
+    case "CallExpr":
+      return `${e.name}(${e.args.map(channelFilterExpr).join(", ")})`;
+    case "TernaryExpr":
+      return `(${channelFilterExpr(e.condition)} ? ${channelFilterExpr(e.consequent)} : ${channelFilterExpr(e.alternate)})`;
+  }
+}
+
+// ─── Flow Saga Runtime ───────────────────────────────────────────────────────
+
+export function emitFlowRuntime(system: IR.IRSystem): string {
+  if (system.flows.length === 0) return "";
+
+  const lines: string[] = [];
+  lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
+  lines.push(`// Saga runtime — implements flow declarations with backward compensation.`);
+  lines.push(`//`);
+  lines.push(`// On step failure, executes compensations for ALL completed steps in reverse order.`);
+  lines.push(``);
+  lines.push(`import { logger } from "./logger";`);
+  lines.push(`import { counter } from "./metrics";`);
+  lines.push(``);
+
+  lines.push(`export interface FlowStep {`);
+  lines.push(`  name: string;`);
+  lines.push(`  action: (ctx: any) => Promise<void>;`);
+  lines.push(`  compensation: ((ctx: any) => Promise<void>) | null;`);
+  lines.push(`}`);
+  lines.push(``);
+
+  lines.push(`export interface FlowResult {`);
+  lines.push(`  ok: boolean;`);
+  lines.push(`  failed_step?: string;`);
+  lines.push(`  compensated: string[];`);
+  lines.push(`  error?: string;`);
+  lines.push(`}`);
+  lines.push(``);
+
+  lines.push(`export async function executeFlow(name: string, steps: FlowStep[], ctx: any): Promise<FlowResult> {`);
+  lines.push(`  const completed: { step: string; compensation: ((c: any) => Promise<void>) | null }[] = [];`);
+  lines.push(``);
+  lines.push(`  for (const step of steps) {`);
+  lines.push(`    try {`);
+  lines.push(`      logger.info("flow_step_started", { event: name + "." + step.name });`);
+  lines.push(`      await step.action(ctx);`);
+  lines.push(`      completed.push({ step: step.name, compensation: step.compensation });`);
+  lines.push(`      counter("flow.step_completed", { flow: name, step: step.name });`);
+  lines.push(`    } catch (e: any) {`);
+  lines.push(`      logger.error("flow_step_failed", { event: name + "." + step.name, metadata: { error: e.message } });`);
+  lines.push(`      counter("flow.step_failed", { flow: name, step: step.name });`);
+  lines.push(``);
+  lines.push(`      // Backward compensation in reverse order`);
+  lines.push(`      const compensated: string[] = [];`);
+  lines.push(`      for (const c of [...completed].reverse()) {`);
+  lines.push(`        if (!c.compensation) continue;`);
+  lines.push(`        try {`);
+  lines.push(`          await c.compensation(ctx);`);
+  lines.push(`          compensated.push(c.step);`);
+  lines.push(`          logger.info("flow_compensated", { event: name + "." + c.step });`);
+  lines.push(`        } catch (compErr: any) {`);
+  lines.push(`          logger.error("flow_compensation_failed", { event: name + "." + c.step, metadata: { error: compErr.message } });`);
+  lines.push(`          // Continue with other compensations even if one fails`);
+  lines.push(`        }`);
+  lines.push(`      }`);
+  lines.push(``);
+  lines.push(`      return { ok: false, failed_step: step.name, compensated, error: e.message };`);
+  lines.push(`    }`);
+  lines.push(`  }`);
+  lines.push(``);
+  lines.push(`  counter("flow.completed", { flow: name });`);
+  lines.push(`  return { ok: true, compensated: [] };`);
+  lines.push(`}`);
+  lines.push(``);
+
+  // Emit each flow's step definitions
+  for (const flow of system.flows) {
+    lines.push(`// Flow: ${flow.name}`);
+    lines.push(`// ctx must contain: { req, res, auth, client? } for transactional flows`);
+    lines.push(`export async function execute_${flow.name}(ctx: { req: any; res: any; auth: any; client?: any }): Promise<FlowResult> {`);
+    lines.push(`  const steps: FlowStep[] = [`);
+    for (const step of flow.steps) {
+      // Parse the action string: "capabilityName(arg1, arg2)"
+      const actionMatch = step.action.match(/^(\w+)\((.*)\)$/);
+      const actionFn = actionMatch ? actionMatch[1] : step.action;
+      const actionArgs = actionMatch ? actionMatch[2] : "";
+
+      lines.push(`    {`);
+      lines.push(`      name: "${step.name}",`);
+      lines.push(`      action: async (ctx) => {`);
+      lines.push(`        // Calls capability: ${step.action}`);
+      lines.push(`        const response = await fetch(\`\${process.env.SERVICE_BASE_URL || "http://localhost:3000"}/${toSnakeCase(actionFn).replace(/_/g, "-")}\`, {`);
+      lines.push(`          method: "POST",`);
+      lines.push(`          headers: { "Content-Type": "application/json", "Authorization": ctx.req.headers.authorization || "" },`);
+      lines.push(`          body: JSON.stringify(ctx.req.body),`);
+      lines.push(`        });`);
+      lines.push(`        if (!response.ok) throw new Error(\`Step ${step.name} failed: \${await response.text()}\`);`);
+      lines.push(`        ctx.${step.name}_result = await response.json();`);
+      lines.push(`      },`);
+
+      if (step.compensation) {
+        const compMatch = step.compensation.match(/^(\w+)\((.*)\)$/);
+        const compFn = compMatch ? compMatch[1] : step.compensation;
+        lines.push(`      compensation: async (ctx) => {`);
+        lines.push(`        // Compensates: ${step.compensation}`);
+        lines.push(`        await fetch(\`\${process.env.SERVICE_BASE_URL || "http://localhost:3000"}/${toSnakeCase(compFn).replace(/_/g, "-")}\`, {`);
+        lines.push(`          method: "POST",`);
+        lines.push(`          headers: { "Content-Type": "application/json", "Authorization": ctx.req.headers.authorization || "" },`);
+        lines.push(`          body: JSON.stringify({ ...ctx.req.body, _compensating: true }),`);
+        lines.push(`        });`);
+        lines.push(`      },`);
+      } else {
+        lines.push(`      compensation: null,`);
+      }
+      lines.push(`    },`);
+    }
+    lines.push(`  ];`);
+    lines.push(`  return executeFlow("${flow.name}", steps, ctx);`);
+    lines.push(`}`);
+    lines.push(``);
+  }
+
+  return lines.join("\n");
+}

package/src/emit_full.ts

@@ -0,0 +1,309 @@
+/**
+ * BoneScript Full Emitter — Produces a complete, runnable project.
+ * Combines schema generation with runtime service code.
+ */
+
+import * as IR from "./ir";
+import { Emitter, EmittedFile } from "./emitter";
+import {
+  emitPackageJson,
+  emitTsConfig,
+  emitDbClient,
+  emitAuthMiddleware,
+  emitEntityRouter,
+  emitStateMachineRuntime,
+  emitIndex,
+  emitMigration,
+} from "./emit_runtime";
+import { emitWebSocketServer } from "./emit_websocket";
+import {
+  emitLogger,
+  emitMetrics,
+  emitHealthChecks,
+  emitFailureRules,
+  emitMigrationDiff,
+} from "./emit_maintenance";
+import { emitFlowRuntime } from "./emit_extras";
+import { emitAlgorithmsFile, collectUsedAlgorithms } from "./emit_composition";
+import { emitExtensionPointStub } from "./extension_manager";
+import * as AST from "./ast";
+import { emitDurableEventBus, emitOutboxSchema } from "./emit_events";
+import { emitBatchExecutor } from "./emit_batch";
+import { emitSourceMapFile, emitDebugHandler } from "./emit_sourcemap";
+import { emitTestSuite } from "./emit_tests";
+import { emitDockerfile, emitDockerignore, emitK8sDeployment, emitGithubActions } from "./emit_deploy";
+
+function toSnakeCase(s: string): string {
+  return s.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+}
+
+export class FullEmitter {
+  private schemaEmitter = new Emitter();
+
+  emit(system: IR.IRSystem): EmittedFile[] {
+    const files: EmittedFile[] = [];
+
+    // 1. Package files
+    files.push({ path: "package.json", content: emitPackageJson(system), language: "json", source_module: "root" });
+    files.push({ path: "tsconfig.json", content: emitTsConfig(), language: "json", source_module: "root" });
+    files.push({ path: ".env.example", content: this.emitEnvExample(system), language: "yaml", source_module: "root" });
+
+    // 2. Source: infrastructure
+    files.push({ path: "src/db.ts", content: emitDbClient(system), language: "typescript", source_module: "infra" });
+    // Durable event bus replaces the old in-process stub
+    files.push({ path: "src/events.ts", content: emitDurableEventBus(system), language: "typescript", source_module: "infra" });
+    // Outbox SQL schema
+    files.push({ path: "migrations/event_outbox.sql", content: emitOutboxSchema(), language: "sql", source_module: "infra" });
+    files.push({ path: "src/auth.ts", content: emitAuthMiddleware(system), language: "typescript", source_module: "infra" });
+    files.push({ path: "src/logger.ts", content: emitLogger(system), language: "typescript", source_module: "infra" });
+    files.push({ path: "src/metrics.ts", content: emitMetrics(), language: "typescript", source_module: "infra" });
+    files.push({ path: "src/health.ts", content: emitHealthChecks(system), language: "typescript", source_module: "infra" });
+    files.push({ path: "src/failure_rules.ts", content: emitFailureRules(system), language: "typescript", source_module: "infra" });
+
+    // 2a. WebSocket server (only if there are realtime channels)
+    const wsContent = emitWebSocketServer(system);
+    if (wsContent) {
+      files.push({ path: "src/websocket.ts", content: wsContent, language: "typescript", source_module: "infra" });
+    }
+
+    // 2b. Flow saga runtime (only if there are flows)
+    const flowContent = emitFlowRuntime(system);
+    if (flowContent) {
+      files.push({ path: "src/flows.ts", content: flowContent, language: "typescript", source_module: "infra" });
+    }
+
+    // 2b2. Batch executor (only if there are batch capabilities)
+    const batchContent = emitBatchExecutor(system);
+    if (batchContent) {
+      files.push({ path: "src/batch.ts", content: batchContent, language: "typescript", source_module: "infra" });
+    }
+
+    // 2c. Migration diff utility (always emitted)
+    files.push({ path: "src/migration_diff.ts", content: emitMigrationDiff(), language: "typescript", source_module: "infra" });
+
+    // 2d. Algorithm implementations (only what's used)
+    const usedAlgorithms = collectUsedAlgorithms(system);
+    if (usedAlgorithms.size > 0) {
+      const algoContent = emitAlgorithmsFile(usedAlgorithms);
+      files.push({ path: "src/algorithms.ts", content: algoContent, language: "typescript", source_module: "algorithms" });
+    } else {
+      files.push({
+        path: "src/algorithms.ts",
+        content: "// No algorithms used in this system.\nexport {};\n",
+        language: "typescript",
+        source_module: "algorithms",
+      });
+    }
+
+    // 2e. Extension points (escape hatches — preserved across recompilation)
+    if (system.extension_points && system.extension_points.length > 0) {
+      const extLines: string[] = [
+        "// Generated by BoneScript compiler.",
+        "// Extension points: implement the functions below.",
+        "// Code between sentinel comments is preserved on recompile.",
+        "// DO NOT remove the sentinel comments.",
+        "",
+      ];
+      for (const ep of system.extension_points) {
+        const params = ep.params.map((p: { name: string; type: string }) => `${p.name}: ${p.type}`).join(", ");
+        const returnType = ep.returns || "void";
+        extLines.push(`/**`);
+        extLines.push(` * Extension point: ${ep.name}`);
+        extLines.push(` * ${ep.stable ? "STABLE: implementation required." : "Optional."}`);
+        extLines.push(` */`);
+        extLines.push(`export function ${ep.name}(${params}): ${returnType} {`);
+        extLines.push(`  // <bonescript:ext:${ep.name}:begin>`);
+        extLines.push(`  throw new Error("Not implemented: ${ep.name}");`);
+        extLines.push(`  // <bonescript:ext:${ep.name}:end>`);
+        extLines.push(`}`);
+        extLines.push("");
+      }
+      files.push({
+        path: "src/extensions.ts",
+        content: extLines.join("\n"),
+        language: "typescript",
+        source_module: "extensions",
+      });
+    }
+
+    // 3. Source: state machines
+    for (const mod of system.modules) {
+      for (const sm of mod.state_machines) {
+        files.push({
+          path: `src/state_machines/${toSnakeCase(sm.entity)}.ts`,
+          content: emitStateMachineRuntime(sm),
+          language: "typescript",
+          source_module: mod.id,
+        });
+      }
+    }
+
+    // 4. Source: route files (CRUD + capabilities)
+    for (const mod of system.modules) {
+      if (mod.kind === "api_service" && mod.models.length > 0) {
+        const content = emitEntityRouter(mod, system);
+        if (content) {
+          files.push({
+            path: `src/routes/${toSnakeCase(mod.models[0].name)}.ts`,
+            content,
+            language: "typescript",
+            source_module: mod.id,
+          });
+        }
+      }
+    }
+
+    // 5. Source: main entry point
+    files.push({ path: "src/index.ts", content: emitIndex(system), language: "typescript", source_module: "root" });
+
+    // 6. SQL migrations — run schema emitter ONCE, then match by model name
+    const schemas: string[] = [];
+    const allSchemaFiles = this.schemaEmitter.emit(system);
+    for (const mod of system.modules) {
+      if (mod.kind === "data_store" || mod.kind === "api_service") {
+        for (const model of mod.models) {
+          const schemaFile = allSchemaFiles.find(f => f.path.includes(toSnakeCase(model.name)) && f.language === "sql");
+          if (schemaFile) {
+            files.push({ ...schemaFile, path: `migrations/${schemaFile.path.replace("schema/", "")}` });
+            schemas.push(schemaFile.content);
+          }
+        }
+      }
+    }
+
+    // 7. Migration runner
+    files.push({ path: "src/migrate.ts", content: emitMigration(system, schemas), language: "typescript", source_module: "infra" });
+
+    // 8. Docker compose for local dev
+    files.push({ path: "docker-compose.yaml", content: this.emitDockerCompose(system), language: "yaml", source_module: "infra" });
+
+    // 9. README
+    files.push({ path: "README.md", content: this.emitReadme(system), language: "yaml", source_module: "root" });
+
+    // 10. Source map + debug handler
+    files.push({ path: `${system.name}.bone.map`, content: emitSourceMapFile(system, `${system.name}.bone`), language: "json", source_module: "root" });
+    files.push({ path: "src/debug.ts", content: emitDebugHandler(system), language: "typescript", source_module: "infra" });
+    files.push({ path: "src/tests.ts", content: emitTestSuite(system), language: "typescript", source_module: "tests" });
+
+    // 11. Deploy targets
+    files.push({ path: "Dockerfile", content: emitDockerfile(system), language: "yaml", source_module: "deploy" });
+    files.push({ path: ".dockerignore", content: emitDockerignore(), language: "yaml", source_module: "deploy" });
+    files.push({ path: "k8s/deployment.yaml", content: emitK8sDeployment(system), language: "yaml", source_module: "deploy" });
+    files.push({ path: ".github/workflows/ci.yaml", content: emitGithubActions(system), language: "yaml", source_module: "deploy" });
+
+    return files;
+  }
+
+  private emitEnvExample(system: IR.IRSystem): string {
+    return `# ${system.name} Environment Variables
+# Copy this file to .env and fill in real values. Never commit .env to source control.
+
+# --- Required in production ---
+# Generate with: node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
+JWT_SECRET=
+
+# --- Database ---
+DATABASE_URL=postgresql://postgres:postgres@localhost:5432/${toSnakeCase(system.name)}
+
+# --- Redis (optional, used by some domain templates) ---
+REDIS_URL=redis://localhost:6379
+
+# --- Server ---
+PORT=3000
+NODE_ENV=development
+
+# --- CORS ---
+# Comma-separated list of allowed origins. Leave empty to disallow all cross-origin requests.
+# Example: ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com
+ALLOWED_ORIGINS=
+
+# --- Event delivery mode ---
+# in_process: in-memory, fast, no durability guarantees (default for development)
+# durable: Postgres-backed transactional outbox (recommended for production)
+EVENT_MODE=in_process
+EVENT_WORKER_INTERVAL_MS=1000
+
+# --- Request timeout ---
+REQUEST_TIMEOUT_MS=30000
+`;
+  }
+
+  private emitDockerCompose(system: IR.IRSystem): string {
+    return `# Generated by BoneScript compiler.
+version: "3.8"
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: ${toSnakeCase(system.name)}
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: postgres
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+
+volumes:
+  pgdata:
+`;
+  }
+
+  private emitReadme(system: IR.IRSystem): string {
+    const apiModules = system.modules.filter(m => m.kind === "api_service");
+    const routes = apiModules
+      .filter(m => m.models.length > 0)
+      .map(m => `- \`/${toSnakeCase(m.models[0].name)}s\` — ${m.name}`)
+      .join("\n");
+
+    return `# ${system.name}
+
+Generated by BoneScript compiler. Source hash: ${system.source_hash}
+
+## Quick Start
+
+\`\`\`bash
+# Start dependencies
+docker compose up -d
+
+# Install
+npm install
+
+# Run migrations
+npm run migrate
+
+# Start server
+npm run dev
+\`\`\`
+
+## API Routes
+
+${routes}
+
+Each route supports:
+- \`GET /\` — List (paginated)
+- \`GET /:id\` — Read
+- \`POST /\` — Create
+- \`PUT /:id\` — Update
+- \`DELETE /:id\` — Delete
+
+Plus capability-specific endpoints.
+
+## Auth
+
+Send a Bearer token in the Authorization header:
+\`\`\`
+Authorization: Bearer <jwt-token>
+\`\`\`
+
+## Environment
+
+Copy \`.env.example\` to \`.env\` and configure.
+`;
+  }
+}