bonescript-compiler 0.2.0

package/src/algorithm_catalog.ts

@@ -0,0 +1,345 @@
+/**
+ * BoneScript Algorithm Catalog (Leap 2)
+ *
+ * A closed catalog of named algorithms. Each entry has:
+ *   - inputs: typed parameters the user must bind
+ *   - outputs: return type
+ *   - description: human-readable explanation
+ *   - emit: function that produces a deterministic implementation
+ *
+ * NEW algorithms can ONLY be added by extending this catalog. The compiler
+ * never invents implementations — it picks from this list.
+ */
+
+export interface AlgorithmSpec {
+  name: string;
+  category: "graph" | "search" | "sort" | "matching" | "scheduling" | "stats" | "crypto";
+  description: string;
+  inputs: { name: string; type: string; description: string }[];
+  output: { type: string; description: string };
+  complexity: string;
+  emit: (bindings: Record<string, string>) => string;
+}
+
+// ─── Algorithm Implementations ───────────────────────────────────────────────
+
+export const CATALOG: Record<string, AlgorithmSpec> = {
+  // ─── Graph Algorithms ──────────────────────────────────────────────────────
+
+  shortest_path: {
+    name: "shortest_path",
+    category: "graph",
+    description: "Dijkstra's algorithm for non-negative weighted shortest path.",
+    inputs: [
+      { name: "graph", type: "map<string, list<{node: string, weight: number}>>", description: "adjacency list" },
+      { name: "source", type: "string", description: "starting node" },
+      { name: "target", type: "string", description: "destination node" },
+    ],
+    output: { type: "{path: string[], distance: number} | null", description: "shortest path or null if unreachable" },
+    complexity: "O((V + E) log V)",
+    emit: (b) => `
+function shortestPath(
+  graph: Map<string, { node: string; weight: number }[]>,
+  source: string,
+  target: string
+): { path: string[]; distance: number } | null {
+  const distances = new Map<string, number>();
+  const previous = new Map<string, string>();
+  const queue: { node: string; distance: number }[] = [];
+
+  for (const node of graph.keys()) distances.set(node, Infinity);
+  distances.set(source, 0);
+  queue.push({ node: source, distance: 0 });
+
+  while (queue.length > 0) {
+    queue.sort((a, b) => a.distance - b.distance);
+    const current = queue.shift()!;
+    if (current.node === target) break;
+    if (current.distance > (distances.get(current.node) ?? Infinity)) continue;
+
+    for (const edge of graph.get(current.node) || []) {
+      const newDist = current.distance + edge.weight;
+      if (newDist < (distances.get(edge.node) ?? Infinity)) {
+        distances.set(edge.node, newDist);
+        previous.set(edge.node, current.node);
+        queue.push({ node: edge.node, distance: newDist });
+      }
+    }
+  }
+
+  if (!previous.has(target) && source !== target) return null;
+  const path: string[] = [];
+  let current: string | undefined = target;
+  while (current !== undefined) {
+    path.unshift(current);
+    current = previous.get(current);
+  }
+  return { path, distance: distances.get(target) || 0 };
+}
+`,
+  },
+
+  topological_sort: {
+    name: "topological_sort",
+    category: "graph",
+    description: "Kahn's algorithm — produces a linear ordering of a DAG.",
+    inputs: [
+      { name: "graph", type: "map<string, string[]>", description: "adjacency list" },
+    ],
+    output: { type: "string[] | null", description: "topological order, or null if cycle exists" },
+    complexity: "O(V + E)",
+    emit: (b) => `
+function topologicalSort(graph: Map<string, string[]>): string[] | null {
+  const inDegree = new Map<string, number>();
+  for (const node of graph.keys()) inDegree.set(node, 0);
+  for (const [, neighbors] of graph) {
+    for (const n of neighbors) inDegree.set(n, (inDegree.get(n) || 0) + 1);
+  }
+
+  const queue: string[] = [];
+  for (const [node, deg] of inDegree) if (deg === 0) queue.push(node);
+
+  const result: string[] = [];
+  while (queue.length > 0) {
+    const node = queue.shift()!;
+    result.push(node);
+    for (const neighbor of graph.get(node) || []) {
+      inDegree.set(neighbor, (inDegree.get(neighbor) || 0) - 1);
+      if (inDegree.get(neighbor) === 0) queue.push(neighbor);
+    }
+  }
+
+  return result.length === graph.size ? result : null;
+}
+`,
+  },
+
+  // ─── Search ───────────────────────────────────────────────────────────────
+
+  binary_search: {
+    name: "binary_search",
+    category: "search",
+    description: "Find target in sorted array.",
+    inputs: [
+      { name: "items", type: "T[]", description: "sorted array" },
+      { name: "target", type: "T", description: "value to find" },
+    ],
+    output: { type: "number", description: "index of target or -1 if not found" },
+    complexity: "O(log n)",
+    emit: (b) => `
+function binarySearch<T>(items: T[], target: T): number {
+  let low = 0, high = items.length - 1;
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    if (items[mid] === target) return mid;
+    if (items[mid] < target) low = mid + 1;
+    else high = mid - 1;
+  }
+  return -1;
+}
+`,
+  },
+
+  // ─── Matching ─────────────────────────────────────────────────────────────
+
+  bipartite_matching: {
+    name: "bipartite_matching",
+    category: "matching",
+    description: "Hopcroft-Karp maximum bipartite matching.",
+    inputs: [
+      { name: "left", type: "string[]", description: "left vertex set" },
+      { name: "right", type: "string[]", description: "right vertex set" },
+      { name: "edges", type: "{from: string, to: string}[]", description: "valid pairings" },
+    ],
+    output: { type: "Map<string, string>", description: "matching from left to right" },
+    complexity: "O(E sqrt(V))",
+    emit: (b) => `
+function bipartiteMatching(
+  left: string[],
+  right: string[],
+  edges: { from: string; to: string }[]
+): Map<string, string> {
+  const adj = new Map<string, string[]>();
+  for (const e of edges) {
+    if (!adj.has(e.from)) adj.set(e.from, []);
+    adj.get(e.from)!.push(e.to);
+  }
+
+  const matchL = new Map<string, string>();
+  const matchR = new Map<string, string>();
+
+  function dfs(u: string, visited: Set<string>): boolean {
+    for (const v of adj.get(u) || []) {
+      if (visited.has(v)) continue;
+      visited.add(v);
+      if (!matchR.has(v) || dfs(matchR.get(v)!, visited)) {
+        matchL.set(u, v);
+        matchR.set(v, u);
+        return true;
+      }
+    }
+    return false;
+  }
+
+  for (const u of left) dfs(u, new Set());
+  return matchL;
+}
+`,
+  },
+
+  // ─── Scheduling ────────────────────────────────────────────────────────────
+
+  round_robin: {
+    name: "round_robin",
+    category: "scheduling",
+    description: "Cyclic assignment of items to workers.",
+    inputs: [
+      { name: "items", type: "T[]", description: "items to assign" },
+      { name: "workers", type: "W[]", description: "workers" },
+    ],
+    output: { type: "Map<W, T[]>", description: "assignments per worker" },
+    complexity: "O(n)",
+    emit: (b) => `
+function roundRobin<T, W>(items: T[], workers: W[]): Map<W, T[]> {
+  const result = new Map<W, T[]>();
+  for (const w of workers) result.set(w, []);
+  for (let i = 0; i < items.length; i++) {
+    const w = workers[i % workers.length];
+    result.get(w)!.push(items[i]);
+  }
+  return result;
+}
+`,
+  },
+
+  // ─── Stats ─────────────────────────────────────────────────────────────────
+
+  weighted_average: {
+    name: "weighted_average",
+    category: "stats",
+    description: "Weighted arithmetic mean.",
+    inputs: [
+      { name: "items", type: "{value: number, weight: number}[]", description: "values with weights" },
+    ],
+    output: { type: "number", description: "weighted average" },
+    complexity: "O(n)",
+    emit: (b) => `
+function weightedAverage(items: { value: number; weight: number }[]): number {
+  let totalWeight = 0;
+  let weightedSum = 0;
+  for (const item of items) {
+    totalWeight += item.weight;
+    weightedSum += item.value * item.weight;
+  }
+  return totalWeight === 0 ? 0 : weightedSum / totalWeight;
+}
+`,
+  },
+
+  percentile: {
+    name: "percentile",
+    category: "stats",
+    description: "Compute the kth percentile of a numeric dataset.",
+    inputs: [
+      { name: "values", type: "number[]", description: "dataset" },
+      { name: "k", type: "number", description: "percentile (0-100)" },
+    ],
+    output: { type: "number", description: "kth percentile value" },
+    complexity: "O(n log n)",
+    emit: (b) => `
+function percentile(values: number[], k: number): number {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const idx = (k / 100) * (sorted.length - 1);
+  const lower = Math.floor(idx);
+  const upper = Math.ceil(idx);
+  if (lower === upper) return sorted[lower];
+  return sorted[lower] + (sorted[upper] - sorted[lower]) * (idx - lower);
+}
+`,
+  },
+
+  // ─── Sort ──────────────────────────────────────────────────────────────────
+
+  rank_by: {
+    name: "rank_by",
+    category: "sort",
+    description: "Stable sort by a numeric scoring function.",
+    inputs: [
+      { name: "items", type: "T[]", description: "items to rank" },
+      { name: "score_fn", type: "(item: T) => number", description: "scoring function" },
+      { name: "order", type: "'asc' | 'desc'", description: "sort direction" },
+    ],
+    output: { type: "T[]", description: "sorted array" },
+    complexity: "O(n log n)",
+    emit: (b) => `
+function rankBy<T>(items: T[], scoreFn: (item: T) => number, order: "asc" | "desc"): T[] {
+  const sign = order === "asc" ? 1 : -1;
+  return [...items].sort((a, b) => sign * (scoreFn(a) - scoreFn(b)));
+}
+`,
+  },
+
+  // ─── Crypto / Hashing ──────────────────────────────────────────────────────
+
+  consistent_hash: {
+    name: "consistent_hash",
+    category: "crypto",
+    description: "Consistent hashing for distributing keys across nodes.",
+    inputs: [
+      { name: "key", type: "string", description: "key to hash" },
+      { name: "nodes", type: "string[]", description: "available nodes" },
+      { name: "replicas", type: "number", description: "virtual nodes per real node" },
+    ],
+    output: { type: "string", description: "node assigned to key" },
+    complexity: "O(N log N) build, O(log N) lookup",
+    emit: (b) => `
+function consistentHash(key: string, nodes: string[], replicas: number = 100): string {
+  if (nodes.length === 0) throw new Error("No nodes available");
+
+  function fnv1a(s: string): number {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+      hash ^= s.charCodeAt(i);
+      hash = (hash + ((hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24))) >>> 0;
+    }
+    return hash;
+  }
+
+  const ring: { hash: number; node: string }[] = [];
+  for (const node of nodes) {
+    for (let i = 0; i < replicas; i++) {
+      ring.push({ hash: fnv1a(node + ":" + i), node });
+    }
+  }
+  ring.sort((a, b) => a.hash - b.hash);
+
+  const target = fnv1a(key);
+  for (const entry of ring) {
+    if (entry.hash >= target) return entry.node;
+  }
+  return ring[0].node;
+}
+`,
+  },
+};
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+export function lookupAlgorithm(name: string): AlgorithmSpec | null {
+  return CATALOG[name] || null;
+}
+
+export function listAlgorithms(): string[] {
+  return Object.keys(CATALOG).sort();
+}
+
+export function listByCategory(): Record<string, string[]> {
+  const result: Record<string, string[]> = {};
+  for (const [name, spec] of Object.entries(CATALOG)) {
+    if (!result[spec.category]) result[spec.category] = [];
+    result[spec.category].push(name);
+  }
+  for (const cat in result) result[cat].sort();
+  return result;
+}

package/src/ast.ts

@@ -0,0 +1,334 @@
+/**
+ * BoneScript Abstract Syntax Tree
+ * Direct representation of the grammar in spec/02_GRAMMAR.peg.
+ * Every node type corresponds to a grammar production.
+ */
+
+import { SourceLocation } from "./lexer";
+
+// ─── Base Node ───────────────────────────────────────────────────────────────
+
+export interface ASTNode {
+  kind: string;
+  loc: SourceLocation;
+}
+
+// ─── Program ─────────────────────────────────────────────────────────────────
+
+export interface ProgramNode extends ASTNode {
+  kind: "Program";
+  systems: SystemDeclNode[];
+}
+
+// ─── System ──────────────────────────────────────────────────────────────────
+
+export interface SystemDeclNode extends ASTNode {
+  kind: "SystemDecl";
+  name: string;
+  domain: string | null;
+  declarations: DeclarationNode[];
+}
+
+export type DeclarationNode =
+  | EntityDeclNode
+  | CapabilityDeclNode
+  | ChannelDeclNode
+  | StoreDeclNode
+  | EventDeclNode
+  | ConstraintDeclNode
+  | PolicyDeclNode
+  | FlowDeclNode
+  | ImportDeclNode
+  | ExtensionPointDeclNode;
+
+// ─── Entity ──────────────────────────────────────────────────────────────────
+
+export interface EntityDeclNode extends ASTNode {
+  kind: "EntityDecl";
+  name: string;
+  owns: FieldNode[];
+  constraints: ExprNode[];
+  states: StateGraphNode | null;
+  auth: string | null;
+  relations: RelationNode[];
+  indexes: string[][];
+  derived: DerivedFieldNode[];
+}
+
+export interface FieldNode extends ASTNode {
+  kind: "Field";
+  name: string;
+  type: TypeExprNode;
+  defaultValue: ExprNode | null;
+}
+
+export interface StateGraphNode extends ASTNode {
+  kind: "StateGraph";
+  nodes: StateNodeEntry[];
+}
+
+export interface StateNodeEntry {
+  name: string;
+  guard: ExprNode | null;
+  transitions: string[]; // names of states this transitions to (via ->)
+  branches: string[];    // names of states this branches to (via |)
+}
+
+export interface RelationNode extends ASTNode {
+  kind: "Relation";
+  name: string;
+  relationType: "has_one" | "has_many" | "belongs_to" | "many_to_many";
+  target: string;
+  cardinality: { min: number; max: number | "*" } | null;
+}
+
+export interface DerivedFieldNode extends ASTNode {
+  kind: "DerivedField";
+  name: string;
+  expr: ExprNode;
+}
+
+// ─── Capability ──────────────────────────────────────────────────────────────
+
+export interface CapabilityDeclNode extends ASTNode {
+  kind: "CapabilityDecl";
+  name: string;
+  params: ParamNode[];
+  requires: ExprNode[];
+  effects: EffectNode[];
+  emits: EmitNode[];
+  sync: string | null;
+  timeout: string | null;
+  retry: RetryPolicyNode | null;
+  idempotent: boolean | null;
+  pipeline: PipelineNode | null;
+  algorithm: AlgorithmNode | null;
+  returns: TypeExprNode | null;
+}
+
+export interface PipelineNode extends ASTNode {
+  kind: "Pipeline";
+  steps: PipelineStepNode[];
+  parallel: boolean;
+  onError: PipelineErrorHandler | null;
+}
+
+export interface PipelineStepNode extends ASTNode {
+  kind: "PipelineStep";
+  call: CallExprNode;
+  bindAs: string | null; // optional `as <name>` to capture output
+}
+
+export interface PipelineErrorHandler {
+  kind: "PipelineErrorHandler";
+  action: "rollback" | "compensate" | "ignore" | "retry";
+  call: CallExprNode | null;
+}
+
+export interface AlgorithmNode extends ASTNode {
+  kind: "Algorithm";
+  name: string;             // catalog entry, e.g. "shortest_path"
+  using: AlgorithmBinding[]; // typed parameter bindings
+}
+
+export interface AlgorithmBinding {
+  param: string;
+  value: ExprNode;
+}
+
+export interface ParamNode extends ASTNode {
+  kind: "Param";
+  name: string;
+  type: TypeExprNode;
+}
+
+export interface EffectNode extends ASTNode {
+  kind: "Effect";
+  target: FieldRefNode;
+  op: "=" | "+=" | "-=";
+  value: ExprNode;
+}
+
+export interface EmitNode extends ASTNode {
+  kind: "Emit";
+  eventName: string;
+  args: ExprNode[];
+}
+
+export interface RetryPolicyNode extends ASTNode {
+  kind: "RetryPolicy";
+  maxAttempts: number | null;
+  backoff: string | null;
+  interval: string | null;
+}
+
+// ─── Channel ─────────────────────────────────────────────────────────────────
+
+export interface ChannelDeclNode extends ASTNode {
+  kind: "ChannelDecl";
+  name: string;
+  transport: string | null;
+  ordering: string | null;
+  participants: TypeExprNode | null;
+  persistence: string | null;
+  filter: ExprNode | null;
+  maxSize: number | null;
+}
+
+// ─── Store ───────────────────────────────────────────────────────────────────
+
+export interface StoreDeclNode extends ASTNode {
+  kind: "StoreDecl";
+  name: string;
+  engine: string | null;
+  schema: FieldNode[];
+  retention: string | null;
+  partition: string | null;
+  replicas: number | null;
+}
+
+// ─── Event ───────────────────────────────────────────────────────────────────
+
+export interface EventDeclNode extends ASTNode {
+  kind: "EventDecl";
+  name: string;
+  payload: FieldNode[];
+  delivery: string | null;
+  ttl: string | null;
+}
+
+// ─── Constraint ──────────────────────────────────────────────────────────────
+
+export interface ConstraintDeclNode extends ASTNode {
+  kind: "ConstraintDecl";
+  name: string;
+  expr: ExprNode;
+}
+
+// ─── Policy ──────────────────────────────────────────────────────────────────
+
+export interface PolicyDeclNode extends ASTNode {
+  kind: "PolicyDecl";
+  name: string;
+  rateLimit: { count: number; per: string } | null;
+  access: string[];
+  audit: boolean | null;
+  encryption: string | null;
+}
+
+// ─── Flow ────────────────────────────────────────────────────────────────────
+
+export interface FlowDeclNode extends ASTNode {
+  kind: "FlowDecl";
+  name: string;
+  steps: FlowStepNode[];
+}
+
+export interface FlowStepNode extends ASTNode {
+  kind: "FlowStep";
+  name: string;
+  action: CallExprNode;
+  compensate: CallExprNode | null;
+}
+
+// ─── Import ──────────────────────────────────────────────────────────────────
+
+export interface ImportDeclNode extends ASTNode {
+  kind: "ImportDecl";
+  name: string;
+  from: string;
+}
+
+// ─── Type Expressions ────────────────────────────────────────────────────────
+
+export type TypeExprNode =
+  | PrimitiveTypeNode
+  | GenericTypeNode
+  | EntityRefTypeNode
+  | TupleTypeNode
+  | UnionTypeNode;
+
+export interface PrimitiveTypeNode extends ASTNode {
+  kind: "PrimitiveType";
+  name: string; // "string" | "uint" | "int" | "float" | "bool" | "timestamp" | "uuid" | "bytes" | "json"
+}
+
+export interface GenericTypeNode extends ASTNode {
+  kind: "GenericType";
+  name: string; // "set" | "list" | "map" | "optional" | "result"
+  typeArgs: TypeExprNode[];
+}
+
+export interface EntityRefTypeNode extends ASTNode {
+  kind: "EntityRefType";
+  name: string;
+}
+
+export interface TupleTypeNode extends ASTNode {
+  kind: "TupleType";
+  elements: TypeExprNode[];
+}
+
+export interface UnionTypeNode extends ASTNode {
+  kind: "UnionType";
+  members: TypeExprNode[];
+}
+
+// ─── Expressions ─────────────────────────────────────────────────────────────
+
+export type ExprNode =
+  | BinaryExprNode
+  | UnaryExprNode
+  | FieldRefNode
+  | LiteralNode
+  | CallExprNode
+  | TernaryExprNode;
+
+export interface BinaryExprNode extends ASTNode {
+  kind: "BinaryExpr";
+  op: string;
+  left: ExprNode;
+  right: ExprNode;
+}
+
+export interface UnaryExprNode extends ASTNode {
+  kind: "UnaryExpr";
+  op: string;
+  operand: ExprNode;
+}
+
+export interface FieldRefNode extends ASTNode {
+  kind: "FieldRef";
+  path: string[]; // e.g., ["player", "inventory", "size"]
+}
+
+export interface LiteralNode extends ASTNode {
+  kind: "Literal";
+  type: "string" | "int" | "float" | "bool" | "none" | "list" | "map";
+  value: string | number | boolean | null | ExprNode[] | [ExprNode, ExprNode][];
+}
+
+export interface CallExprNode extends ASTNode {
+  kind: "CallExpr";
+  name: string;
+  args: ExprNode[];
+}
+
+export interface TernaryExprNode extends ASTNode {
+  kind: "TernaryExpr";
+  condition: ExprNode;
+  consequent: ExprNode;
+  alternate: ExprNode;
+}
+
+// ─── Extension Point ─────────────────────────────────────────────────────────
+// Declares a named hook that the user fills in with custom TypeScript.
+// The compiler reserves a region in generated code that survives recompilation.
+
+export interface ExtensionPointDeclNode extends ASTNode {
+  kind: "ExtensionPointDecl";
+  name: string;
+  params: ParamNode[];
+  returns: TypeExprNode | null;
+  stable: boolean;  // if true, compiler errors if implementation is missing
+}