bonescript-compiler 0.2.0

package/src/scaffold.ts

@@ -0,0 +1,375 @@
+/**
+ * BoneScript Project Scaffolder — `bone init`
+ * Creates a new BoneScript project with sensible defaults for a chosen domain.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+export type ScaffoldDomain =
+  | "multiplayer_game"
+  | "saas_platform"
+  | "iot_system"
+  | "social_network"
+  | "marketplace"
+  | "realtime_collaboration";
+
+const TEMPLATES: Record<ScaffoldDomain, string> = {
+  multiplayer_game: `system MyGame {
+  domain: multiplayer_game
+
+  entity Player {
+    owns: [
+      username: string,
+      score: uint
+    ]
+    constraints: [
+      username.unique,
+      username.length in 3..32,
+      score >= 0
+    ]
+    states: active -> suspended | deleted
+    auth: jwt
+  }
+
+  capability award_points(player: Player, points: uint) {
+    requires: [points > 0, player.state == "active"]
+    effects: [player.score += points]
+    sync: eventual
+  }
+
+  store PlayerStore {
+    engine: postgresql
+    schema: {
+      id: uuid,
+      username: string,
+      score: uint,
+      state: string
+    }
+  }
+
+  channel game_lobby {
+    transport: websocket
+    ordering: causal
+    participants: set<Player>
+    persistence: last_100
+  }
+}
+`,
+
+  saas_platform: `system MySaaS {
+  domain: saas_platform
+
+  entity Tenant {
+    owns: [
+      name: string,
+      plan: string,
+      active: bool
+    ]
+    constraints: [
+      name.length in 1..100,
+      plan in ["free", "pro", "enterprise"]
+    ]
+    states: trialing -> active -> suspended | cancelled
+    auth: oauth2
+  }
+
+  entity User {
+    owns: [
+      email: string,
+      tenant_id: uuid,
+      role: string
+    ]
+    constraints: [
+      email.unique,
+      role in ["admin", "member", "viewer"]
+    ]
+    auth: oauth2
+  }
+
+  capability invite_user(tenant: Tenant, email: string, role: string) {
+    requires: [tenant.state == "active", role in ["admin", "member", "viewer"]]
+    effects: []
+    emits: UserInvited
+    sync: transactional
+  }
+
+  event UserInvited {
+    payload: {
+      tenant_id: uuid,
+      email: string,
+      role: string,
+      invited_at: timestamp
+    }
+    delivery: at_least_once
+    ttl: 7d
+  }
+
+  store TenantStore {
+    engine: postgresql
+    schema: {
+      id: uuid,
+      name: string,
+      plan: string,
+      active: bool,
+      state: string
+    }
+  }
+}
+`,
+
+  iot_system: `system MyIoT {
+  domain: iot_system
+
+  entity Device {
+    owns: [
+      serial: string,
+      firmware_version: string,
+      last_seen: timestamp,
+      battery: uint
+    ]
+    constraints: [
+      serial.unique,
+      battery <= 100
+    ]
+    states: online -> offline -> retired
+    auth: apikey
+  }
+
+  entity Reading {
+    owns: [
+      device_id: uuid,
+      sensor: string,
+      value: float,
+      recorded_at: timestamp
+    ]
+  }
+
+  capability ingest_reading(device: Device, sensor: string, value: float) {
+    requires: [device.state == "online"]
+    effects: [device.last_seen = now()]
+    emits: ReadingRecorded
+    sync: eventual
+  }
+
+  event ReadingRecorded {
+    payload: {
+      device_id: uuid,
+      sensor: string,
+      value: float
+    }
+    delivery: at_least_once
+    ttl: 1d
+  }
+
+  store DeviceStore {
+    engine: dynamodb
+    schema: {
+      id: uuid,
+      serial: string,
+      firmware_version: string,
+      battery: uint,
+      state: string
+    }
+  }
+}
+`,
+
+  social_network: `system MySocial {
+  domain: social_network
+
+  entity User {
+    owns: [
+      handle: string,
+      display_name: string,
+      followers: set<uuid>,
+      following: set<uuid>
+    ]
+    constraints: [
+      handle.unique,
+      handle.length in 3..30
+    ]
+    auth: oauth2
+  }
+
+  entity Post {
+    owns: [
+      author_id: uuid,
+      content: string,
+      likes: uint
+    ]
+    constraints: [
+      content.length in 1..500
+    ]
+  }
+
+  capability follow_user(follower: User, target: User) {
+    requires: [follower != target]
+    effects: [
+      follower.following += target.id,
+      target.followers += follower.id
+    ]
+    sync: eventual
+  }
+
+  channel feed {
+    transport: websocket
+    ordering: causal
+    participants: set<User>
+    persistence: last_100
+  }
+}
+`,
+
+  marketplace: `system MyMarket {
+  domain: marketplace
+
+  entity Listing {
+    owns: [
+      seller_id: uuid,
+      title: string,
+      price: uint,
+      stock: uint
+    ]
+    constraints: [
+      title.length in 1..200,
+      price > 0,
+      stock >= 0
+    ]
+    states: draft -> active -> sold_out | archived
+    auth: oauth2
+  }
+
+  entity Order {
+    owns: [
+      buyer_id: uuid,
+      listing_id: uuid,
+      quantity: uint,
+      total: uint
+    ]
+    states: pending -> paid -> shipped -> delivered | cancelled
+  }
+
+  capability purchase(buyer: User, listing: Listing, qty: uint) {
+    requires: [
+      listing.state == "active",
+      listing.stock >= qty
+    ]
+    effects: [
+      listing.stock -= qty
+    ]
+    emits: OrderCreated
+    sync: transactional
+  }
+
+  event OrderCreated {
+    payload: {
+      order_id: uuid,
+      buyer_id: uuid,
+      listing_id: uuid,
+      total: uint
+    }
+    delivery: exactly_once
+    ttl: 30d
+  }
+}
+`,
+
+  realtime_collaboration: `system MyCollab {
+  domain: realtime_collaboration
+
+  entity Document {
+    owns: [
+      title: string,
+      owner_id: uuid,
+      content: json,
+      version: uint
+    ]
+    constraints: [
+      version >= 1
+    ]
+    auth: jwt
+  }
+
+  entity Cursor {
+    owns: [
+      document_id: uuid,
+      user_id: uuid,
+      position: uint,
+      color: string
+    ]
+  }
+
+  capability apply_change(doc: Document, user: User, change: json) {
+    requires: [doc.owner_id == user.id or doc.collaborators contains user.id]
+    effects: [
+      doc.version += 1,
+      doc.content = change
+    ]
+    emits: DocumentChanged
+    sync: realtime
+  }
+
+  channel doc_session {
+    transport: websocket
+    ordering: causal
+    participants: set<User>
+    persistence: last_1000
+  }
+
+  event DocumentChanged {
+    payload: {
+      document_id: uuid,
+      user_id: uuid,
+      version: uint
+    }
+    delivery: at_least_once
+    ttl: 1d
+  }
+}
+`,
+};
+
+export interface ScaffoldOptions {
+  name: string;
+  domain: ScaffoldDomain;
+  outDir: string;
+}
+
+export function scaffold(opts: ScaffoldOptions): { created: string[] } {
+  const created: string[] = [];
+
+  if (!fs.existsSync(opts.outDir)) {
+    fs.mkdirSync(opts.outDir, { recursive: true });
+  }
+
+  // Main .bone file
+  const mainFile = path.join(opts.outDir, `${opts.name}.bone`);
+  let content = TEMPLATES[opts.domain];
+  // Replace placeholder system name with provided name
+  content = content.replace(/^system \w+ \{/, `system ${pascalCase(opts.name)} {`);
+  fs.writeFileSync(mainFile, content, "utf-8");
+  created.push(mainFile);
+
+  // README
+  const readmePath = path.join(opts.outDir, "README.md");
+  fs.writeFileSync(readmePath, `# ${opts.name}
+
+BoneScript project (domain: ${opts.domain}).
+
+## Compile
+
+\`\`\`bash
+bone compile ${opts.name}.bone
+\`\`\`
+
+The output will be written to \`./output/\` as a complete Node.js project.
+`, "utf-8");
+  created.push(readmePath);
+
+  return { created };
+}
+
+function pascalCase(s: string): string {
+  return s.replace(/(^|[-_\s])(\w)/g, (_, __, c) => c.toUpperCase());
+}

package/src/solver.ts

@@ -0,0 +1,330 @@
+/**
+ * BoneScript Constraint Solver — Stage 5 of the compilation pipeline.
+ * Implements spec/06_CONSTRAINT_SOLVER.md.
+ *
+ * Resolves all underspecified aspects of the IR into concrete decisions.
+ * Uses ONLY: ontology implication rules, domain defaults, structural necessity.
+ * NO heuristics. NO probabilistic matching.
+ *
+ * Phases:
+ *   1. Collect — gather all constraints
+ *   2. Normalize — canonical form
+ *   3. Propagate — unit propagation
+ *   4. Check — verify consistency
+ *   5. Complete — fill remaining with defaults
+ *   6. Verify — final pass
+ */
+
+import * as IR from "./ir";
+
+// ─── Domain Defaults ─────────────────────────────────────────────────────────
+
+interface DomainDefaults {
+  auth: string;
+  engine: string;
+  session_engine: string;
+  sync: string;
+  channel_transport: string;
+  channel_ordering: string;
+  channel_persistence: string;
+  session_ttl_ms: number;
+  max_connections: number;
+  rate_limit: number;
+}
+
+const DOMAIN_DEFAULTS: Record<string, DomainDefaults> = {
+  multiplayer_game: {
+    auth: "jwt",
+    engine: "postgresql",
+    session_engine: "redis",
+    sync: "realtime",
+    channel_transport: "websocket",
+    channel_ordering: "causal",
+    channel_persistence: "last_100",
+    session_ttl_ms: 3_600_000,
+    max_connections: 10000,
+    rate_limit: 1000,
+  },
+  saas_platform: {
+    auth: "oauth2",
+    engine: "postgresql",
+    session_engine: "redis",
+    sync: "eventual",
+    channel_transport: "sse",
+    channel_ordering: "fifo",
+    channel_persistence: "full",
+    session_ttl_ms: 86_400_000,
+    max_connections: 5000,
+    rate_limit: 500,
+  },
+  iot_system: {
+    auth: "apikey",
+    engine: "dynamodb",
+    session_engine: "redis",
+    sync: "eventual",
+    channel_transport: "grpc_stream",
+    channel_ordering: "fifo",
+    channel_persistence: "last_1000",
+    session_ttl_ms: 7_200_000,
+    max_connections: 100000,
+    rate_limit: 10000,
+  },
+  social_network: {
+    auth: "oauth2",
+    engine: "postgresql",
+    session_engine: "redis",
+    sync: "eventual",
+    channel_transport: "websocket",
+    channel_ordering: "causal",
+    channel_persistence: "last_100",
+    session_ttl_ms: 86_400_000,
+    max_connections: 50000,
+    rate_limit: 2000,
+  },
+  marketplace: {
+    auth: "oauth2",
+    engine: "postgresql",
+    session_engine: "redis",
+    sync: "transactional",
+    channel_transport: "sse",
+    channel_ordering: "fifo",
+    channel_persistence: "full",
+    session_ttl_ms: 3_600_000,
+    max_connections: 10000,
+    rate_limit: 1000,
+  },
+  realtime_collaboration: {
+    auth: "jwt",
+    engine: "postgresql",
+    session_engine: "redis",
+    sync: "realtime",
+    channel_transport: "websocket",
+    channel_ordering: "causal",
+    channel_persistence: "full",
+    session_ttl_ms: 7_200_000,
+    max_connections: 10000,
+    rate_limit: 5000,
+  },
+};
+
+const FALLBACK_DEFAULTS: DomainDefaults = {
+  auth: "jwt",
+  engine: "postgresql",
+  session_engine: "redis",
+  sync: "eventual",
+  channel_transport: "websocket",
+  channel_ordering: "fifo",
+  channel_persistence: "none",
+  session_ttl_ms: 3_600_000,
+  max_connections: 10000,
+  rate_limit: 1000,
+};
+
+// ─── Solver Output ───────────────────────────────────────────────────────────
+
+export interface SolverResult {
+  resolution: Record<string, string>;
+  assumptions: string[];
+  warnings: string[];
+  errors: string[];
+}
+
+// ─── Solver ──────────────────────────────────────────────────────────────────
+
+export class ConstraintSolver {
+  solve(system: IR.IRSystem): SolverResult {
+    const resolution: Record<string, string> = {};
+    const assumptions: string[] = [];
+    const warnings: string[] = [];
+    const errors: string[] = [];
+
+    const defaults = DOMAIN_DEFAULTS[system.domain || ""] || FALLBACK_DEFAULTS;
+
+    if (!system.domain) {
+      assumptions.push("No domain specified. Using fallback defaults.");
+    } else {
+      assumptions.push(`Domain '${system.domain}' selected. Applying domain defaults.`);
+    }
+
+    // ─── Phase 1: Collect ────────────────────────────────────────────────────
+
+    // Collect all unresolved variables from modules
+    const unresolvedVars: Map<string, string | null> = new Map();
+
+    for (const mod of system.modules) {
+      const prefix = `${mod.name}`;
+
+      if (mod.kind === "data_store") {
+        const engine = mod.config["engine"] as string | undefined;
+        if (!engine) {
+          unresolvedVars.set(`${prefix}.engine`, null);
+        } else {
+          resolution[`${prefix}.engine`] = engine;
+        }
+        if (mod.config["replicas"] === undefined) {
+          unresolvedVars.set(`${prefix}.replicas`, null);
+        }
+      }
+
+      if (mod.kind === "api_service") {
+        const authMethod = mod.config["auth_method"] as string | undefined;
+        if (!authMethod || authMethod === "none") {
+          unresolvedVars.set(`${prefix}.auth_method`, null);
+        } else {
+          resolution[`${prefix}.auth_method`] = authMethod;
+        }
+      }
+
+      if (mod.kind === "realtime_service") {
+        const transport = mod.config["transport"] as string | undefined;
+        if (!transport) unresolvedVars.set(`${prefix}.transport`, null);
+        else resolution[`${prefix}.transport`] = transport;
+
+        const ordering = mod.config["ordering"] as string | undefined;
+        if (!ordering) unresolvedVars.set(`${prefix}.ordering`, null);
+        else resolution[`${prefix}.ordering`] = ordering;
+
+        const persistence = mod.config["persistence"] as string | undefined;
+        if (!persistence || persistence === "none") {
+          unresolvedVars.set(`${prefix}.persistence`, null);
+        } else {
+          resolution[`${prefix}.persistence`] = persistence;
+        }
+      }
+
+      if (mod.kind === "gateway") {
+        if (!mod.config["rate_limit"]) {
+          unresolvedVars.set(`${prefix}.rate_limit`, null);
+        }
+      }
+    }
+
+    // ─── Phase 2: Normalize ──────────────────────────────────────────────────
+    // (constraints are already in canonical form from the IR)
+
+    // ─── Phase 3: Propagate ──────────────────────────────────────────────────
+
+    // Apply domain defaults to unresolved variables
+    for (const [varName] of unresolvedVars) {
+      const parts = varName.split(".");
+      const prop = parts[parts.length - 1];
+
+      switch (prop) {
+        case "engine":
+          resolution[varName] = defaults.engine;
+          assumptions.push(`${varName} = ${defaults.engine} (domain default)`);
+          break;
+        case "auth_method":
+          resolution[varName] = defaults.auth;
+          assumptions.push(`${varName} = ${defaults.auth} (domain default)`);
+          break;
+        case "transport":
+          resolution[varName] = defaults.channel_transport;
+          assumptions.push(`${varName} = ${defaults.channel_transport} (domain default)`);
+          break;
+        case "ordering":
+          resolution[varName] = defaults.channel_ordering;
+          assumptions.push(`${varName} = ${defaults.channel_ordering} (domain default)`);
+          break;
+        case "persistence":
+          resolution[varName] = defaults.channel_persistence;
+          assumptions.push(`${varName} = ${defaults.channel_persistence} (domain default)`);
+          break;
+        case "rate_limit":
+          resolution[varName] = String(defaults.rate_limit);
+          assumptions.push(`${varName} = ${defaults.rate_limit} (domain default)`);
+          break;
+        case "replicas":
+          resolution[varName] = "1";
+          assumptions.push(`${varName} = 1 (minimum default)`);
+          break;
+        default:
+          warnings.push(`Unresolved variable '${varName}' has no default.`);
+      }
+    }
+
+    // ─── Implication Rules ───────────────────────────────────────────────────
+
+    // Rule: If any module has auth != none, system needs a session store
+    const hasAuth = system.modules.some(m =>
+      m.config["authenticated"] === true || (m.config["auth_method"] && m.config["auth_method"] !== "none")
+    );
+    if (hasAuth) {
+      const hasSessionStore = system.modules.some(m =>
+        m.kind === "data_store" && (m.name.toLowerCase().includes("session") || m.config["engine"] === "redis")
+      );
+      if (!hasSessionStore) {
+        resolution["implied.session_store"] = "required";
+        resolution["implied.session_store.engine"] = defaults.session_engine;
+        resolution["implied.session_store.ttl_ms"] = String(defaults.session_ttl_ms);
+        assumptions.push(`Auth detected → session store required (${defaults.session_engine}, TTL=${defaults.session_ttl_ms}ms)`);
+      }
+    }
+
+    // Rule: If any realtime_service exists, event_bus is implied
+    const hasRealtime = system.modules.some(m => m.kind === "realtime_service");
+    if (hasRealtime) {
+      resolution["implied.event_bus"] = "required";
+      resolution["implied.event_bus.engine"] = "redis_pubsub";
+      assumptions.push("Realtime service detected → event bus required (redis_pubsub)");
+    }
+
+    // Rule: If events exist with delivery=exactly_once, transactional outbox is implied
+    const hasExactlyOnce = system.events.some(e => e.delivery === "exactly_once");
+    if (hasExactlyOnce) {
+      resolution["implied.outbox"] = "required";
+      resolution["implied.outbox.engine"] = defaults.engine;
+      assumptions.push("exactly_once delivery detected → transactional outbox required");
+    }
+
+    // Rule: If flows exist, saga coordinator is implied
+    if (system.flows.length > 0) {
+      resolution["implied.saga_coordinator"] = "required";
+      assumptions.push("Flow declarations detected → saga coordinator required");
+    }
+
+    // ─── Phase 4: Check Consistency ──────────────────────────────────────────
+
+    // Check: total ordering + polling is invalid
+    for (const mod of system.modules) {
+      if (mod.kind === "realtime_service") {
+        const transport = resolution[`${mod.name}.transport`] || mod.config["transport"];
+        const ordering = resolution[`${mod.name}.ordering`] || mod.config["ordering"];
+        if (ordering === "total" && transport === "polling") {
+          errors.push(`Exclusion rule violated: ${mod.name} has ordering=total with transport=polling (incompatible)`);
+        }
+      }
+    }
+
+    // Check: realtime sync requires at_least_once delivery
+    for (const ev of system.events) {
+      if (ev.delivery === "at_most_once") {
+        const sourceModule = system.modules.find(m => m.id === ev.source);
+        if (sourceModule && sourceModule.kind === "realtime_service") {
+          warnings.push(`Event '${ev.name}' uses at_most_once delivery on a realtime service. Consider at_least_once.`);
+        }
+      }
+    }
+
+    // ─── Phase 5: Complete ───────────────────────────────────────────────────
+
+    // Global resolution entries
+    resolution["system.name"] = system.name;
+    resolution["system.version"] = system.version;
+    resolution["system.domain"] = system.domain || "generic";
+    resolution["system.default_timeout_ms"] = "30000";
+    resolution["system.default_page_size"] = "50";
+    resolution["system.max_connections"] = String(defaults.max_connections);
+
+    // ─── Phase 6: Verify ─────────────────────────────────────────────────────
+
+    // All variables should now be resolved
+    for (const [varName] of unresolvedVars) {
+      if (!resolution[varName]) {
+        errors.push(`C002: Unresolvable variable '${varName}' — no default available. Programmer must specify.`);
+      }
+    }
+
+    return { resolution, assumptions, warnings, errors };
+  }
+}