bonescript-compiler 0.2.0

package/src/extension_manager.ts

@@ -0,0 +1,187 @@
+/**
+ * BoneScript Extension Manager
+ *
+ * Handles the escape hatch system: extension_point declarations.
+ *
+ * How it works:
+ * 1. Compiler emits a stub with sentinel comments around the implementation region.
+ * 2. On recompile, the merger reads the existing output file and extracts any
+ *    user code between the sentinels.
+ * 3. The user's code is re-injected into the newly generated file.
+ * 4. If stable: true and no implementation exists, compilation fails.
+ *
+ * Sentinel format (must be unique and parseable):
+ *   // <bonescript:ext:NAME:begin>
+ *   ... user code here ...
+ *   // <bonescript:ext:NAME:end>
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import * as AST from "./ast";
+
+// ─── Sentinel Helpers ────────────────────────────────────────────────────────
+
+export function beginSentinel(name: string): string {
+  return `// <bonescript:ext:${name}:begin>`;
+}
+
+export function endSentinel(name: string): string {
+  return `// <bonescript:ext:${name}:end>`;
+}
+
+export function isStubImplementation(code: string): boolean {
+  return code.trim() === "" || code.includes("throw new Error(\"Not implemented:");
+}
+
+// ─── Stub Generator ──────────────────────────────────────────────────────────
+
+function toTsType(irType: string): string {
+  const map: Record<string, string> = {
+    string: "string", uint: "number", int: "number", float: "number",
+    bool: "boolean", timestamp: "Date", uuid: "string", bytes: "Buffer", json: "unknown",
+  };
+  if (map[irType]) return map[irType];
+  const m = irType.match(/^(list|set)<(.+)>$/);
+  if (m) return `${toTsType(m[2])}[]`;
+  const om = irType.match(/^optional<(.+)>$/);
+  if (om) return `${toTsType(om[1])} | null`;
+  return irType;
+}
+
+function serializeType(t: AST.TypeExprNode): string {
+  switch (t.kind) {
+    case "PrimitiveType": return t.name;
+    case "GenericType": return `${t.name}<${t.typeArgs.map(serializeType).join(", ")}>`;
+    case "EntityRefType": return t.name;
+    case "TupleType": return `(${t.elements.map(serializeType).join(", ")})`;
+    case "UnionType": return t.members.map(serializeType).join(" | ");
+  }
+}
+
+export function emitExtensionPointStub(ext: AST.ExtensionPointDeclNode): string {
+  const params = ext.params.map(p => `${p.name}: ${toTsType(serializeType(p.type))}`).join(", ");
+  const returnType = ext.returns ? toTsType(serializeType(ext.returns)) : "void";
+  const lines: string[] = [];
+
+  lines.push(`/**`);
+  lines.push(` * Extension point: ${ext.name}`);
+  lines.push(` * ${ext.stable ? "STABLE — implementation required." : "Optional — stub used if not implemented."}`);
+  lines.push(` * Params: ${ext.params.map(p => `${p.name}: ${serializeType(p.type)}`).join(", ") || "none"}`);
+  lines.push(` * Returns: ${ext.returns ? serializeType(ext.returns) : "void"}`);
+  lines.push(` */`);
+  lines.push(`export function ${ext.name}(${params}): ${returnType} {`);
+  lines.push(`  ${beginSentinel(ext.name)}`);
+  lines.push(`  throw new Error("Not implemented: ${ext.name}");`);
+  lines.push(`  ${endSentinel(ext.name)}`);
+  lines.push(`}`);
+
+  return lines.join("\n");
+}
+
+// ─── Extension Merger ────────────────────────────────────────────────────────
+// Reads an existing generated file and extracts user implementations.
+
+export interface ExtractedImpl {
+  name: string;
+  code: string;
+  isStub: boolean;
+}
+
+export function extractImplementations(existingContent: string): Map<string, ExtractedImpl> {
+  const result = new Map<string, ExtractedImpl>();
+  const beginPattern = /\/\/ <bonescript:ext:([^:]+):begin>/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = beginPattern.exec(existingContent)) !== null) {
+    const name = match[1];
+    const beginIdx = match.index + match[0].length;
+    const endMarker = endSentinel(name);
+    const endIdx = existingContent.indexOf(endMarker, beginIdx);
+
+    if (endIdx === -1) continue;
+
+    const code = existingContent.slice(beginIdx, endIdx).trim();
+    result.set(name, {
+      name,
+      code,
+      isStub: isStubImplementation(code),
+    });
+  }
+
+  return result;
+}
+
+export function mergeImplementations(
+  newContent: string,
+  existingImpls: Map<string, ExtractedImpl>
+): string {
+  let result = newContent;
+
+  for (const [name, impl] of existingImpls) {
+    if (impl.isStub) continue; // don't restore stubs
+
+    const begin = beginSentinel(name);
+    const end = endSentinel(name);
+    const beginIdx = result.indexOf(begin);
+    const endIdx = result.indexOf(end, beginIdx);
+
+    if (beginIdx === -1 || endIdx === -1) continue;
+
+    const before = result.slice(0, beginIdx + begin.length);
+    const after = result.slice(endIdx);
+    result = `${before}\n  ${impl.code}\n  ${after}`;
+  }
+
+  return result;
+}
+
+// ─── Validation ──────────────────────────────────────────────────────────────
+
+export interface ExtensionValidationError {
+  name: string;
+  message: string;
+}
+
+export function validateExtensions(
+  extensions: AST.ExtensionPointDeclNode[],
+  existingImpls: Map<string, ExtractedImpl>
+): ExtensionValidationError[] {
+  const errors: ExtensionValidationError[] = [];
+
+  for (const ext of extensions) {
+    if (!ext.stable) continue;
+
+    const impl = existingImpls.get(ext.name);
+    if (!impl || impl.isStub) {
+      errors.push({
+        name: ext.name,
+        message: `Extension point '${ext.name}' is marked stable: true but has no implementation. ` +
+          `Add your implementation between the sentinel comments in the generated file.`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+// ─── File-Level Merge ────────────────────────────────────────────────────────
+// Called by the emitter when writing output files.
+
+export function mergeWithExisting(
+  newContent: string,
+  outputPath: string,
+  extensions: AST.ExtensionPointDeclNode[]
+): { content: string; validationErrors: ExtensionValidationError[] } {
+  let existingImpls = new Map<string, ExtractedImpl>();
+
+  if (fs.existsSync(outputPath)) {
+    const existing = fs.readFileSync(outputPath, "utf-8");
+    existingImpls = extractImplementations(existing);
+  }
+
+  const validationErrors = validateExtensions(extensions, existingImpls);
+  const content = mergeImplementations(newContent, existingImpls);
+
+  return { content, validationErrors };
+}

package/src/formatter.ts

@@ -0,0 +1,297 @@
+/**
+ * BoneScript Formatter — `bone fmt`
+ * Canonicalizes whitespace and formatting in .bone source files.
+ *
+ * Rules:
+ * - 2-space indentation
+ * - One declaration per logical block, separated by one blank line
+ * - Field lists: one per line if more than 2, otherwise inline
+ * - Constraints: one per line
+ * - Trailing newline at end of file
+ * - LF line endings
+ */
+
+import * as AST from "./ast";
+
+export class Formatter {
+  private out: string[] = [];
+  private indent = 0;
+
+  format(program: AST.ProgramNode): string {
+    this.out = [];
+    this.indent = 0;
+
+    for (let i = 0; i < program.systems.length; i++) {
+      this.formatSystem(program.systems[i]);
+      if (i < program.systems.length - 1) this.line("");
+    }
+
+    return this.out.join("\n") + "\n";
+  }
+
+  private line(s: string) {
+    this.out.push("  ".repeat(this.indent) + s);
+  }
+
+  private blank() {
+    this.out.push("");
+  }
+
+  private formatSystem(sys: AST.SystemDeclNode) {
+    this.line(`system ${sys.name} {`);
+    this.indent++;
+
+    if (sys.domain) {
+      this.line(`domain: ${sys.domain}`);
+      this.blank();
+    }
+
+    for (let i = 0; i < sys.declarations.length; i++) {
+      this.formatDeclaration(sys.declarations[i]);
+      if (i < sys.declarations.length - 1) this.blank();
+    }
+
+    this.indent--;
+    this.line(`}`);
+  }
+
+  private formatDeclaration(decl: AST.DeclarationNode) {
+    switch (decl.kind) {
+      case "EntityDecl": this.formatEntity(decl); break;
+      case "CapabilityDecl": this.formatCapability(decl); break;
+      case "ChannelDecl": this.formatChannel(decl); break;
+      case "StoreDecl": this.formatStore(decl); break;
+      case "EventDecl": this.formatEvent(decl); break;
+      case "ConstraintDecl": this.formatConstraint(decl); break;
+      case "PolicyDecl": this.formatPolicy(decl); break;
+      case "FlowDecl": this.formatFlow(decl); break;
+      case "ImportDecl": this.formatImport(decl); break;
+      case "ExtensionPointDecl": this.formatExtensionPoint(decl); break;
+    }
+  }
+
+  private formatEntity(e: AST.EntityDeclNode) {
+    this.line(`entity ${e.name} {`);
+    this.indent++;
+
+    if (e.owns.length > 0) {
+      if (e.owns.length <= 2) {
+        const fields = e.owns.map(f => `${f.name}: ${this.formatType(f.type)}`).join(", ");
+        this.line(`owns: [${fields}]`);
+      } else {
+        this.line(`owns: [`);
+        this.indent++;
+        for (let i = 0; i < e.owns.length; i++) {
+          const f = e.owns[i];
+          const comma = i < e.owns.length - 1 ? "," : "";
+          this.line(`${f.name}: ${this.formatType(f.type)}${comma}`);
+        }
+        this.indent--;
+        this.line(`]`);
+      }
+    }
+
+    if (e.constraints.length > 0) {
+      this.line(`constraints: [`);
+      this.indent++;
+      for (let i = 0; i < e.constraints.length; i++) {
+        const comma = i < e.constraints.length - 1 ? "," : "";
+        this.line(`${this.formatExpr(e.constraints[i])}${comma}`);
+      }
+      this.indent--;
+      this.line(`]`);
+    }
+
+    if (e.states) {
+      const path = e.states.nodes.map(n => n.name).join(" -> ");
+      this.line(`states: ${path}`);
+    }
+
+    if (e.auth) this.line(`auth: ${e.auth}`);
+
+    for (const idx of e.indexes) {
+      this.line(`index: [${idx.join(", ")}]`);
+    }
+
+    this.indent--;
+    this.line(`}`);
+  }
+
+  private formatCapability(c: AST.CapabilityDeclNode) {
+    const params = c.params.map(p => `${p.name}: ${this.formatType(p.type)}`).join(", ");
+    this.line(`capability ${c.name}(${params}) {`);
+    this.indent++;
+
+    if (c.requires.length > 0) {
+      this.line(`requires: [`);
+      this.indent++;
+      for (let i = 0; i < c.requires.length; i++) {
+        const comma = i < c.requires.length - 1 ? "," : "";
+        this.line(`${this.formatExpr(c.requires[i])}${comma}`);
+      }
+      this.indent--;
+      this.line(`]`);
+    }
+
+    if (c.effects.length > 0) {
+      this.line(`effects: [`);
+      this.indent++;
+      for (let i = 0; i < c.effects.length; i++) {
+        const eff = c.effects[i];
+        const comma = i < c.effects.length - 1 ? "," : "";
+        this.line(`${eff.target.path.join(".")} ${eff.op} ${this.formatExpr(eff.value)}${comma}`);
+      }
+      this.indent--;
+      this.line(`]`);
+    }
+
+    if (c.emits.length > 0) {
+      const emits = c.emits.map(e => {
+        const args = e.args.map(a => this.formatExpr(a)).join(", ");
+        return args ? `${e.eventName}(${args})` : e.eventName;
+      }).join(", ");
+      this.line(`emits: ${emits}`);
+    }
+
+    if (c.sync) this.line(`sync: ${c.sync}`);
+    if (c.timeout) this.line(`timeout: ${c.timeout}`);
+    if (c.idempotent !== null) this.line(`idempotent: ${c.idempotent}`);
+
+    this.indent--;
+    this.line(`}`);
+  }
+
+  private formatChannel(c: AST.ChannelDeclNode) {
+    this.line(`channel ${c.name} {`);
+    this.indent++;
+    if (c.transport) this.line(`transport: ${c.transport}`);
+    if (c.ordering) this.line(`ordering: ${c.ordering}`);
+    if (c.participants) this.line(`participants: ${this.formatType(c.participants)}`);
+    if (c.persistence) this.line(`persistence: ${c.persistence}`);
+    if (c.maxSize !== null) this.line(`max_size: ${c.maxSize}`);
+    if (c.filter) this.line(`filter: ${this.formatExpr(c.filter)}`);
+    this.indent--;
+    this.line(`}`);
+  }
+
+  private formatStore(s: AST.StoreDeclNode) {
+    this.line(`store ${s.name} {`);
+    this.indent++;
+    if (s.engine) this.line(`engine: ${s.engine}`);
+    if (s.schema.length > 0) {
+      this.line(`schema: {`);
+      this.indent++;
+      for (let i = 0; i < s.schema.length; i++) {
+        const f = s.schema[i];
+        const comma = i < s.schema.length - 1 ? "," : "";
+        this.line(`${f.name}: ${this.formatType(f.type)}${comma}`);
+      }
+      this.indent--;
+      this.line(`}`);
+    }
+    if (s.retention) this.line(`retention: ${s.retention}`);
+    if (s.partition) this.line(`partition: ${s.partition}`);
+    if (s.replicas !== null) this.line(`replicas: ${s.replicas}`);
+    this.indent--;
+    this.line(`}`);
+  }
+
+  private formatEvent(e: AST.EventDeclNode) {
+    this.line(`event ${e.name} {`);
+    this.indent++;
+    if (e.payload.length > 0) {
+      this.line(`payload: {`);
+      this.indent++;
+      for (let i = 0; i < e.payload.length; i++) {
+        const f = e.payload[i];
+        const comma = i < e.payload.length - 1 ? "," : "";
+        this.line(`${f.name}: ${this.formatType(f.type)}${comma}`);
+      }
+      this.indent--;
+      this.line(`}`);
+    }
+    if (e.delivery) this.line(`delivery: ${e.delivery}`);
+    if (e.ttl) this.line(`ttl: ${e.ttl}`);
+    this.indent--;
+    this.line(`}`);
+  }
+
+  private formatConstraint(c: AST.ConstraintDeclNode) {
+    this.line(`constraint ${c.name}: ${this.formatExpr(c.expr)}`);
+  }
+
+  private formatPolicy(p: AST.PolicyDeclNode) {
+    this.line(`policy ${p.name} {`);
+    this.indent++;
+    if (p.rateLimit) this.line(`rate_limit: ${p.rateLimit.count} per ${p.rateLimit.per}`);
+    if (p.access.length > 0) this.line(`access: [${p.access.join(", ")}]`);
+    if (p.audit !== null) this.line(`audit: ${p.audit}`);
+    if (p.encryption) this.line(`encryption: ${p.encryption}`);
+    this.indent--;
+    this.line(`}`);
+  }
+
+  private formatFlow(f: AST.FlowDeclNode) {
+    this.line(`flow ${f.name} {`);
+    this.indent++;
+    for (let i = 0; i < f.steps.length; i++) {
+      const step = f.steps[i];
+      const args = step.action.args.map(a => this.formatExpr(a)).join(", ");
+      this.line(`step ${step.name}: ${step.action.name}(${args})`);
+      if (step.compensate) {
+        const cargs = step.compensate.args.map(a => this.formatExpr(a)).join(", ");
+        this.indent++;
+        this.line(`compensate: ${step.compensate.name}(${cargs})`);
+        this.indent--;
+      }
+      if (i < f.steps.length - 1) this.blank();
+    }
+    this.indent--;
+    this.line(`}`);
+  }
+
+  private formatImport(i: AST.ImportDeclNode) {
+    this.line(`import ${i.name} from "${i.from}"`);
+  }
+
+  private formatType(t: AST.TypeExprNode): string {
+    switch (t.kind) {
+      case "PrimitiveType": return t.name;
+      case "GenericType": return `${t.name}<${t.typeArgs.map(a => this.formatType(a)).join(", ")}>`;
+      case "EntityRefType": return t.name;
+      case "TupleType": return `(${t.elements.map(e => this.formatType(e)).join(", ")})`;
+      case "UnionType": return t.members.map(m => this.formatType(m)).join(" | ");
+    }
+  }
+
+  private formatExpr(e: AST.ExprNode): string {
+    switch (e.kind) {
+      case "Literal":
+        if (e.type === "string") return `"${e.value}"`;
+        if (e.type === "list") return `[${(e.value as AST.ExprNode[]).map(v => this.formatExpr(v)).join(", ")}]`;
+        if (e.type === "none") return "none";
+        return String(e.value);
+      case "FieldRef":
+        return e.path.join(".");
+      case "BinaryExpr":
+        if (e.op === "..") return `${this.formatExpr(e.left)}..${this.formatExpr(e.right)}`;
+        return `${this.formatExpr(e.left)} ${e.op} ${this.formatExpr(e.right)}`;
+      case "UnaryExpr":
+        return `${e.op} ${this.formatExpr(e.operand)}`;
+      case "CallExpr":
+        return `${e.name}(${e.args.map(a => this.formatExpr(a)).join(", ")})`;
+      case "TernaryExpr":
+        return `${this.formatExpr(e.condition)} ? ${this.formatExpr(e.consequent)} : ${this.formatExpr(e.alternate)}`;
+    }
+  }
+
+  private formatExtensionPoint(e: AST.ExtensionPointDeclNode) {
+    const params = e.params.map(p => `${p.name}: ${this.formatType(p.type)}`).join(", ");
+    this.line(`extension_point ${e.name}(${params}) {`);
+    this.indent++;
+    if (e.returns) this.line(`returns: ${this.formatType(e.returns)}`);
+    this.line(`stable: ${e.stable}`);
+    this.indent--;
+    this.line(`}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * BoneScript Compiler — Public API
+ * Import this module to use the compiler programmatically.
+ */
+
+// Core pipeline
+export { Lexer, LexerError, TokenKind } from "./lexer";
+export type { Token, SourceLocation } from "./lexer";
+export { Parser, ParseError } from "./parser";
+export { RecoveringParser } from "./parser_recovery";
+export type { RecoveredParseResult } from "./parser_recovery";
+export { TypeChecker } from "./typechecker";
+export type { TypeError } from "./typechecker";
+export { Lowering } from "./lowering";
+export { ConstraintSolver } from "./solver";
+export type { SolverResult } from "./solver";
+export { FullEmitter } from "./emit_full";
+export type { EmittedFile } from "./emitter";
+export { Verifier } from "./verifier";
+export type { VerifyResult, VerifyIssue } from "./verifier";
+export { optimize } from "./optimizer";
+export type { OptimizationResult } from "./optimizer";
+export { ModuleLoader } from "./module_loader";
+export type { LoadResult } from "./module_loader";
+export { Formatter } from "./formatter";
+export { scaffold } from "./scaffold";
+export type { ScaffoldDomain } from "./scaffold";
+
+// AST types
+export * as AST from "./ast";
+
+// IR types
+export * as IR from "./ir";
+
+// Algorithm catalog
+export { lookupAlgorithm, listAlgorithms, listByCategory } from "./algorithm_catalog";
+
+// Extension system
+export { mergeWithExisting, extractImplementations, validateExtensions } from "./extension_manager";
+
+/**
+ * Convenience function: compile a .bone source string to files.
+ */
+export async function compile(source: string, sourceFile: string = "program.bone"): Promise<{
+  files: { path: string; content: string; language: string; source_module: string }[];
+  errors: string[];
+  warnings: string[];
+}> {
+  const { createHash } = await import("crypto");
+  const { Lexer: L } = await import("./lexer");
+  const { Parser: P } = await import("./parser");
+  const { TypeChecker: TC } = await import("./typechecker");
+  const { Lowering: Lo } = await import("./lowering");
+  const { ConstraintSolver: CS } = await import("./solver");
+  const { FullEmitter: FE } = await import("./emit_full");
+  const { optimize: opt } = await import("./optimizer");
+
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const tokens = new L(source).tokenize();
+  const ast = new P(tokens).parse();
+
+  const typeErrors = new TC().check(ast);
+  for (const err of typeErrors) {
+    errors.push(`${err.code} at ${err.loc.line}:${err.loc.column}: ${err.message}`);
+  }
+  if (errors.length > 0) return { files: [], errors, warnings };
+
+  const hash = createHash("sha256").update(source).digest("hex").slice(0, 16);
+  const irSystems = new Lo().lower(ast, hash);
+
+  for (let i = 0; i < irSystems.length; i++) {
+    const result = opt(irSystems[i]);
+    irSystems[i] = result.system;
+    const solveResult = new CS().solve(irSystems[i]);
+    irSystems[i].resolution = solveResult.resolution;
+    for (const w of solveResult.warnings) warnings.push(w);
+  }
+
+  const files: { path: string; content: string; language: string; source_module: string }[] = [];
+  const emitter = new FE();
+  for (const sys of irSystems) {
+    files.push(...emitter.emit(sys));
+  }
+
+  return { files, errors, warnings };
+}