codexivo 0.2.0 → 1.0.0

package/src/flow.ts

@@ -0,0 +1,385 @@
+import type * as ast from './syntax/ast';
+import type { Span } from './syntax/token';
+import { printExpression, printStatement } from './printer';
+
+/**
+ * Diagrama de flujo generado desde el AST. Aquí se decide qué nodos y aristas existen; el sitio solo los
+ * acomoda (con ELK o dagre) y los dibuja. Con los eventos `paso` y `decide` de la máquina (`nodeId`), el sitio
+ * sabe qué nodo iluminar: cada `nodeId` que emite la ejecución aparece en `astIds` de algún nodo del grafo.
+ */
+
+export type FlowNodeKind = 'inicio' | 'fin' | 'proceso' | 'decisión' | 'llamada' | 'entrada' | 'salida' | 'retorno';
+
+export interface FlowNode {
+  id: string;
+  kind: FlowNodeKind;
+  /** Texto corto para mostrar, generado desde el AST. Si se agruparon sentencias, una por línea. */
+  label: string;
+  /** Nodos del AST que representa: la sentencia y, en una decisión, también su condición. */
+  astIds: number[];
+  spans: Span[];
+  /** Orden sugerido para acomodar el grafo: distancia desde el inicio sin contar las vueltas de los bucles. */
+  rank: number;
+  /** En una llamada a un procedimiento del programa: su nombre, para enlazar con `procedures`. */
+  procedure?: string;
+}
+
+/**
+ * - `normal`: sigue a la siguiente sentencia (o entra o sale de un bucle);
+ * - `vuelta`: regresa al inicio de un bucle;
+ * - `romper`, `continuar`, `regresa`: saltos explícitos.
+ */
+export type FlowEdgeKind = 'normal' | 'vuelta' | 'romper' | 'continuar' | 'regresa';
+
+/** Etiqueta de una arista que sale de una decisión. */
+export type FlowEdgeLabel = 'sí' | 'no' | 'repetir' | 'salir';
+
+export interface FlowEdge {
+  id: string;
+  from: string;
+  to: string;
+  kind: FlowEdgeKind;
+  label?: FlowEdgeLabel;
+}
+
+export interface FlowGraph {
+  nodes: FlowNode[];
+  edges: FlowEdge[];
+  /** Con `expandProcedures`, el grafo de cada procedimiento con nombre del programa. */
+  procedures?: Array<{ name: string; astId: number; graph: FlowGraph }>;
+}
+
+export interface FlowOptions {
+  /** Junta sentencias simples consecutivas (asignaciones, declaraciones) en un solo nodo de proceso. */
+  group?: boolean;
+  /** Genera también el grafo de cada procedimiento con nombre y marca las llamadas a ellos. */
+  expandProcedures?: boolean;
+  /** Recorta las etiquetas largas a esta cantidad de caracteres, con `…`. Por defecto no se recortan. */
+  maxLabelLength?: number;
+}
+
+interface Pending {
+  from: string;
+  kind?: FlowEdgeKind;
+  label?: FlowEdgeLabel;
+}
+
+interface Loop {
+  breaks: Pending[];
+  continues: Pending[];
+}
+
+const INPUT = new Set(['leer', 'leer_número', 'leer_numero']);
+const OUTPUT = new Set(['imprimir']);
+
+/** `f` o `dominio.f`: la ruta de un nombre, si la expresión es solo eso. */
+const path = (node: ast.Expression): string | undefined => {
+  if (node.kind === 'Identifier') return node.name;
+  if (node.kind === 'Index' && node.dot && node.index.kind === 'StringLiteral') {
+    const object = path(node.object);
+    return object && `${object}.${node.index.value}`;
+  }
+  return undefined;
+};
+
+/** Nombre (o ruta) del procedimiento al que llama una expresión, si es una llamada directa. */
+const calledName = (node: ast.Expression | undefined): string | undefined =>
+  node?.kind === 'Call' ? path(node.callee) : undefined;
+
+class Builder {
+  readonly nodes: FlowNode[] = [];
+  readonly edges: FlowEdge[] = [];
+  private readonly loops: Loop[] = [];
+  private readonly returns: Pending[] = [];
+  /** Último nodo de proceso, al que se le pueden juntar sentencias con `group`. */
+  private groupable?: string;
+
+  constructor(
+    private readonly options: FlowOptions,
+    private readonly procedures: Set<string>,
+  ) {}
+
+  private label(text: string): string {
+    const max = this.options.maxLabelLength;
+    return max && text.length > max ? `${text.slice(0, Math.max(1, max - 1))}…` : text;
+  }
+
+  node(kind: FlowNodeKind, label: string, astNodes: Array<{ id: number; span: Span }>): string {
+    const id = `n${this.nodes.length}`;
+    this.nodes.push({
+      id,
+      kind,
+      label: this.label(label),
+      astIds: astNodes.map(node => node.id),
+      spans: astNodes.map(node => node.span),
+      rank: 0,
+    });
+    this.groupable = undefined;
+    return id;
+  }
+
+  connect(pending: Pending[], to: string): void {
+    for (const { from, kind = 'normal', label } of pending) {
+      this.edges.push({ id: `e${this.edges.length}`, from, to, kind, ...(label ? { label } : {}) });
+    }
+  }
+
+  /** Un nodo simple con sus aristas de entrada; regresa la arista pendiente que sale de él. */
+  private simple(kind: FlowNodeKind, statement: ast.Statement, incoming: Pending[], procedure?: string): Pending[] {
+    const groupable = kind === 'proceso' && this.options.group;
+    const last = this.groupable ? this.nodes.find(node => node.id === this.groupable) : undefined;
+    if (groupable && last && incoming.length === 1 && incoming[0]!.from === last.id && !incoming[0]!.label) {
+      last.label = `${last.label}\n${this.label(printStatement(statement))}`;
+      last.astIds.push(statement.id);
+      last.spans.push(statement.span);
+      return incoming;
+    }
+    const id = this.node(kind, printStatement(statement), [statement]);
+    if (procedure) this.nodes[this.nodes.length - 1]!.procedure = procedure;
+    this.connect(incoming, id);
+    if (groupable) this.groupable = id;
+    return [{ from: id }];
+  }
+
+  private kindOf(statement: ast.Statement): { kind: FlowNodeKind; procedure?: string } {
+    const expression =
+      statement.kind === 'ExpressionStatement'
+        ? statement.expression
+        : statement.kind === 'VariableDeclaration' || statement.kind === 'Assignment'
+          ? statement.value
+          : undefined;
+    const name = calledName(expression);
+    if (name && INPUT.has(name)) return { kind: 'entrada' };
+    if (name && OUTPUT.has(name) && statement.kind === 'ExpressionStatement') return { kind: 'salida' };
+    if (name && this.procedures.has(name)) {
+      return this.options.expandProcedures ? { kind: 'llamada', procedure: name } : { kind: 'llamada' };
+    }
+    if (statement.kind === 'ExpressionStatement' && name) return { kind: 'llamada' };
+    return { kind: 'proceso' };
+  }
+
+  statements(list: ast.Statement[], incoming: Pending[]): Pending[] {
+    let current = incoming;
+    for (const statement of list) current = this.statement(statement, current);
+    return current;
+  }
+
+  private loop(body: () => Pending[]): { out: Pending[]; loop: Loop } {
+    const loop: Loop = { breaks: [], continues: [] };
+    this.loops.push(loop);
+    const out = body();
+    this.loops.pop();
+    return { out, loop };
+  }
+
+  private back(pending: Pending[], kind: FlowEdgeKind = 'vuelta'): Pending[] {
+    return pending.map(edge => (edge.kind && edge.kind !== 'normal' ? edge : { ...edge, kind }));
+  }
+
+  private statement(statement: ast.Statement, incoming: Pending[]): Pending[] {
+    switch (statement.kind) {
+      case 'FunctionDeclaration':
+        // Se crea al entrar al bloque, no en este punto; su grafo va en `procedures`.
+        return incoming;
+      case 'Domain': {
+        // Un dominio solo declara: es un paso de proceso que representa todas sus declaraciones.
+        const members: ast.Statement[] = [];
+        const collect = (domain: ast.Domain) => {
+          members.push(domain);
+          for (const member of domain.body.statements) {
+            if (member.kind === 'VariableDeclaration') members.push(member);
+            else if (member.kind === 'Domain') collect(member);
+          }
+        };
+        collect(statement);
+        const id = this.node('proceso', printStatement(statement), members);
+        this.connect(incoming, id);
+        return [{ from: id }];
+      }
+      case 'VariableDeclaration':
+      case 'Assignment':
+      case 'Increment':
+      case 'ExpressionStatement': {
+        const { kind, procedure } = this.kindOf(statement);
+        return this.simple(kind, statement, incoming, procedure);
+      }
+      case 'Return': {
+        const id = this.node('retorno', printStatement(statement), [statement]);
+        this.connect(incoming, id);
+        this.returns.push({ from: id, kind: 'regresa' });
+        return [];
+      }
+      case 'Break':
+      case 'Continue': {
+        const id = this.node('proceso', printStatement(statement), [statement]);
+        this.connect(incoming, id);
+        const loop = this.loops[this.loops.length - 1];
+        if (statement.kind === 'Break') loop?.breaks.push({ from: id, kind: 'romper' });
+        else loop?.continues.push({ from: id, kind: 'continuar' });
+        return [];
+      }
+      case 'Block':
+        return this.statements(statement.statements, incoming);
+      case 'If': {
+        let pending = incoming;
+        const out: Pending[] = [];
+        statement.branches.forEach((branch, index) => {
+          const astNodes = index === 0 ? [statement, branch.condition] : [branch.condition];
+          const id = this.node('decisión', printExpression(branch.condition), astNodes);
+          this.connect(pending, id);
+          out.push(...this.statements(branch.body.statements, [{ from: id, label: 'sí' }]));
+          pending = [{ from: id, label: 'no' }];
+        });
+        if (statement.alternative) out.push(...this.statements(statement.alternative.statements, pending));
+        else out.push(...pending);
+        return out;
+      }
+      case 'While': {
+        const id = this.node('decisión', printExpression(statement.condition), [statement, statement.condition]);
+        this.connect(incoming, id);
+        const { out, loop } = this.loop(() => this.statements(statement.body.statements, [{ from: id, label: 'sí' }]));
+        this.connect(this.back([...out, ...loop.continues]), id);
+        return [{ from: id, label: 'no' }, ...loop.breaks];
+      }
+      case 'DoUntil': {
+        // El cuerpo va primero; la entrada al bucle se conecta al primer nodo que cree.
+        const first = this.nodes.length;
+        const { out, loop } = this.loop(() => this.statements(statement.body.statements, incoming));
+        const id = this.node('decisión', `hasta_que ${printExpression(statement.condition)}`, [
+          statement,
+          statement.condition,
+        ]);
+        this.connect([...out, ...loop.continues], id);
+        const start = this.nodes[first]?.id ?? id;
+        this.connect([{ from: id, label: 'no', kind: 'vuelta' }], start);
+        if (start === id) this.edges.pop(); // cuerpo vacío: la vuelta sería un lazo sobre sí misma
+        return [{ from: id, label: 'sí' }, ...loop.breaks];
+      }
+      case 'For': {
+        let pending = incoming;
+        const initOwner: ast.Statement[] = [];
+        if (statement.init) {
+          this.groupable = undefined;
+          const before = this.nodes.length;
+          pending = this.statement(statement.init, pending);
+          // El paso del `para` se ilumina en su inicio.
+          this.nodes[before]?.astIds.unshift(statement.id);
+          this.nodes[before]?.spans.unshift(statement.span);
+        } else {
+          initOwner.push(statement);
+        }
+        const condition = statement.condition;
+        const id = this.node('decisión', condition ? printExpression(condition) : 'verdadero', [
+          ...initOwner,
+          ...(condition ? [condition] : []),
+        ]);
+        this.connect(pending, id);
+        const { out, loop } = this.loop(() => this.statements(statement.body.statements, [{ from: id, label: 'sí' }]));
+        let tail = [...out, ...loop.continues];
+        if (statement.update) tail = this.statement(statement.update, tail);
+        this.connect(this.back(tail), id);
+        return [...(condition ? [{ from: id, label: 'no' as const }] : []), ...loop.breaks];
+      }
+      case 'Repeat':
+      case 'ForRange':
+      case 'ForEach': {
+        const head =
+          statement.kind === 'Repeat'
+            ? statement.count
+            : statement.kind === 'ForRange'
+              ? statement.to
+              : statement.iterable;
+        const id = this.node('decisión', printStatement(statement), [statement, head]);
+        this.connect(incoming, id);
+        const { out, loop } = this.loop(() =>
+          this.statements(statement.body.statements, [{ from: id, label: 'repetir' }]),
+        );
+        this.connect(this.back([...out, ...loop.continues]), id);
+        return [{ from: id, label: 'salir' }, ...loop.breaks];
+      }
+    }
+  }
+
+  finish(start: string, out: Pending[]): void {
+    const end = this.node('fin', 'fin', []);
+    this.connect([...out, ...this.returns], end);
+    // Rango: distancia más larga desde el inicio sin contar vueltas (el grafo sin ellas no tiene ciclos).
+    const forward = this.edges.filter(edge => edge.kind !== 'vuelta' && edge.kind !== 'continuar');
+    const rank = new Map<string, number>([[start, 0]]);
+    for (let changed = true, guard = 0; changed && guard <= this.nodes.length; guard++) {
+      changed = false;
+      for (const edge of forward) {
+        const next = (rank.get(edge.from) ?? -1) + 1;
+        if (rank.has(edge.from) && next > (rank.get(edge.to) ?? -1)) {
+          rank.set(edge.to, next);
+          changed = true;
+        }
+      }
+    }
+    for (const node of this.nodes) node.rank = rank.get(node.id) ?? 0;
+  }
+}
+
+/** Procedimientos con nombre declarados en estas sentencias, con su ruta si están en un dominio. */
+const procedureNames = (statements: ast.Statement[], known: Iterable<string> = []): Set<string> => {
+  const names = new Set(known);
+  const visit = (list: ast.Statement[], prefix: string) => {
+    for (const statement of list) {
+      if (statement.kind === 'FunctionDeclaration') names.add(`${prefix}${statement.name.name}`);
+      if (statement.kind === 'Domain') visit(statement.body.statements, `${prefix}${statement.name.name}.`);
+    }
+  };
+  visit(statements, '');
+  return names;
+};
+
+/**
+ * Grafo de flujo de un programa o de un procedimiento. El AST tiene que venir sin errores de sintaxis.
+ */
+export const flowGraph = (
+  root: ast.Program | ast.FunctionLiteral | ast.FunctionDeclaration,
+  options: FlowOptions = {},
+): FlowGraph => graphOf(root, options, []);
+
+const graphOf = (
+  root: ast.Program | ast.FunctionLiteral | ast.FunctionDeclaration,
+  options: FlowOptions,
+  known: Iterable<string>,
+): FlowGraph => {
+  const statements =
+    root.kind === 'Program'
+      ? root.statements
+      : root.kind === 'FunctionDeclaration'
+        ? root.function.body.statements
+        : root.body.statements;
+  const names = procedureNames(statements, known);
+  const builder = new Builder(options, names);
+  const title =
+    root.kind === 'Program'
+      ? 'inicio'
+      : root.kind === 'FunctionDeclaration'
+        ? printStatement(root)
+        : `procedimiento(${root.params.map(param => param.name).join(', ')})`;
+  const start = builder.node('inicio', title, root.kind === 'Program' ? [] : [root]);
+  const out = builder.statements(statements, [{ from: start }]);
+  builder.finish(start, out);
+
+  const graph: FlowGraph = { nodes: builder.nodes, edges: builder.edges };
+  if (options.expandProcedures) {
+    graph.procedures = [];
+    // Los procedimientos de un dominio se nombran con su ruta: `calculadora.suma`.
+    const visit = (list: ast.Statement[], prefix: string) => {
+      for (const statement of list) {
+        if (statement.kind === 'Domain') visit(statement.body.statements, `${prefix}${statement.name.name}.`);
+        if (statement.kind !== 'FunctionDeclaration') continue;
+        graph.procedures!.push({
+          name: `${prefix}${statement.name.name}`,
+          astId: statement.id,
+          graph: graphOf(statement, options, names),
+        });
+      }
+    };
+    visit(statements, '');
+  }
+  return graph;
+};

package/src/index.ts

@@ -23,7 +23,59 @@ export type {
   SerializedValue,
   Snapshot,
   FrameSnapshot,
+  HeapEntry,
 } from './runtime/machine';
 export { natives } from './runtime/builtins';
 export { repr, show, typeOf, equals, Scope, WAIT_FOR_INPUT } from './runtime/values';
-export type { Value, ListValue, ProcedureValue, NativeValue, NativeContext, TypeName } from './runtime/values';
+export type {
+  Value,
+  ListValue,
+  DictValue,
+  DictKey,
+  ProcedureValue,
+  NativeValue,
+  NativeContext,
+  TypeName,
+} from './runtime/values';
+
+export { createWorld, validateWorld, checkGoal, DIRECTIONS } from './world';
+export type {
+  World,
+  WorldDefinition,
+  WorldState,
+  WorldGoal,
+  WorldValidationError,
+  GoalDifference,
+  Wall,
+  BeeperPile,
+  BeeperCount,
+  Robot,
+  RobotEvent,
+  RobotSnapshot,
+  RobotAction,
+  Direction,
+} from './world';
+
+export { catalog } from './catalog';
+export type { Catalog, KeywordGroup, OperatorEntry, ProcedureEntry, ConstantEntry, ErrorEntry } from './catalog';
+export type { ProcedureDoc, ProcedureExample, ProcedureLevel, ProcedureCategory } from './runtime/values';
+
+export { flowGraph } from './flow';
+export type { FlowGraph, FlowNode, FlowEdge, FlowNodeKind, FlowEdgeKind, FlowEdgeLabel, FlowOptions } from './flow';
+export { printExpression, printStatement } from './printer';
+
+export { evaluarReto } from './challenge';
+export type { Challenge, ChallengeCase, ChallengeResult, CaseResult, JsonValue } from './challenge';
+export { createSandbox } from './sandbox';
+export type { Sandbox, WorkerLike } from './sandbox';
+export { SandboxHost } from './sandbox-host';
+export type {
+  SandboxOptions,
+  SandboxRequest,
+  SandboxResponse,
+  EventDetail,
+  Loaded,
+  Progress,
+  Stopped,
+  StopReason,
+} from './sandbox-host';

package/src/printer.ts

@@ -0,0 +1,133 @@
+import type * as ast from './syntax/ast';
+import { repr } from './runtime/values';
+
+/**
+ * Convierte nodos del AST en texto corto de Codexivo (`suma += i`, `i <= 10`). Lo usan el diagrama de flujo y
+ * cualquier vista que necesite mostrar una parte del programa sin copiar el código original.
+ */
+
+/** Precedencia de la §4.1 (mayor agrupa primero), para poner paréntesis solo donde hacen falta. */
+const precedence = (node: ast.Expression): number => {
+  switch (node.kind) {
+    case 'Logical':
+      return node.operator === 'o' ? 1 : 2;
+    case 'Unary':
+      return node.operator === 'no' ? 3 : 7;
+    case 'Binary':
+      switch (node.operator) {
+        case '==':
+        case '!=':
+        case '<':
+        case '>':
+        case '<=':
+        case '>=':
+          return 4;
+        case '+':
+        case '-':
+          return 5;
+        case '^':
+          return 8;
+        default:
+          return 6;
+      }
+    default:
+      return 10;
+  }
+};
+
+const operand = (node: ast.Expression, parent: number, wrapEqual: boolean): string => {
+  const text = printExpression(node);
+  const own = precedence(node);
+  return own < parent || (wrapEqual && own === parent) ? `(${text})` : text;
+};
+
+export const printExpression = (node: ast.Expression): string => {
+  switch (node.kind) {
+    case 'NumberLiteral':
+    case 'StringLiteral':
+    case 'BooleanLiteral':
+      return repr(node.value);
+    case 'NullLiteral':
+      return 'nulo';
+    case 'Identifier':
+      return node.name;
+    case 'ListLiteral':
+      return `[${node.elements.map(printExpression).join(', ')}]`;
+    case 'DictLiteral':
+      return node.entries.length === 0
+        ? '{}'
+        : `{ ${node.entries
+            .map(entry => {
+              const key = printExpression(entry.key);
+              const literal = entry.key.kind === 'StringLiteral' || entry.key.kind === 'NumberLiteral';
+              return `${literal ? key : `(${key})`}: ${printExpression(entry.value)}`;
+            })
+            .join(', ')} }`;
+    case 'Unary': {
+      const own = precedence(node);
+      const inner = operand(node.operand, own, false);
+      return node.operator === 'no' ? `no ${inner}` : `-${inner}`;
+    }
+    case 'Binary':
+    case 'Logical': {
+      const own = precedence(node);
+      // `^` agrupa a la derecha; los demás, a la izquierda. Las comparaciones no se encadenan.
+      const right = node.kind === 'Binary' && node.operator === '^';
+      const compare = own === 4;
+      const left = operand(node.left, own, right || compare);
+      const rightText = operand(node.right, own, !right || compare);
+      return `${left} ${node.operator} ${rightText}`;
+    }
+    case 'Call':
+      return `${operand(node.callee, 10, false)}(${node.args.map(printExpression).join(', ')})`;
+    case 'Index':
+      if (node.dot && node.index.kind === 'StringLiteral')
+        return `${operand(node.object, 10, false)}.${node.index.value}`;
+      return `${operand(node.object, 10, false)}[${printExpression(node.index)}]`;
+    case 'FunctionLiteral':
+      return `procedimiento(${node.params.map(param => param.name).join(', ')}) { … }`;
+  }
+};
+
+/**
+ * Una sentencia en una línea. Las compuestas se resumen con su encabezado: `si (x > 0)`, `repetir 3 veces`,
+ * `para_cada x en lista`.
+ */
+export const printStatement = (node: ast.Statement): string => {
+  switch (node.kind) {
+    case 'VariableDeclaration':
+      return `${node.constant ? 'constante' : 'variable'} ${node.name.name} = ${printExpression(node.value)}`;
+    case 'FunctionDeclaration':
+      return `procedimiento ${node.name.name}(${node.function.params.map(param => param.name).join(', ')})`;
+    case 'Assignment':
+      return `${printExpression(node.target)} ${node.operator} ${printExpression(node.value)}`;
+    case 'Increment':
+      return `${printExpression(node.target)}${node.operator}`;
+    case 'ExpressionStatement':
+      return printExpression(node.expression);
+    case 'Return':
+      return node.value ? `regresa ${printExpression(node.value)}` : 'regresa';
+    case 'Domain':
+      return `dominio ${node.name.name}`;
+    case 'Break':
+      return 'romper';
+    case 'Continue':
+      return 'continuar';
+    case 'Block':
+      return '{ … }';
+    case 'If':
+      return `si (${printExpression(node.branches[0]!.condition)})`;
+    case 'While':
+      return `mientras (${printExpression(node.condition)})`;
+    case 'DoUntil':
+      return `hasta_que (${printExpression(node.condition)})`;
+    case 'For':
+      return `para (${node.condition ? printExpression(node.condition) : ''})`;
+    case 'Repeat':
+      return `repetir ${printExpression(node.count)} veces`;
+    case 'ForRange':
+      return `para ${node.variable.name} desde ${printExpression(node.from)} hasta ${printExpression(node.to)}${node.step ? ` con_paso ${printExpression(node.step)}` : ''}`;
+    case 'ForEach':
+      return `para_cada ${node.variable.name}${node.value ? `, ${node.value.name}` : ''} en ${printExpression(node.iterable)}`;
+  }
+};