codexivo 0.0.0-stage → 0.2.0

package/src/errors.ts

@@ -0,0 +1,56 @@
+import type { Span } from './syntax/token';
+
+export type ErrorKind = 'léxico' | 'sintaxis' | 'ejecución' | 'límite';
+
+export interface ErrorInfo {
+  kind: ErrorKind;
+  code: string;
+  message: string;
+  hint?: string;
+  span?: Span;
+  /** Nombres de los procedimientos activos cuando ocurrió el error, del más externo al más interno. */
+  callStack?: string[];
+}
+
+/**
+ * Error de Codexivo. Siempre describe qué pasó (`message`) y, cuando es posible,
+ * qué revisar (`hint`) y dónde (`span`).
+ */
+export class CodexivoError extends Error implements ErrorInfo {
+  kind: ErrorKind;
+  code: string;
+  hint?: string;
+  span?: Span;
+  callStack?: string[];
+
+  constructor(info: ErrorInfo) {
+    super(info.message);
+    this.name = 'CodexivoError';
+    this.kind = info.kind;
+    this.code = info.code;
+    this.hint = info.hint;
+    this.span = info.span;
+    this.callStack = info.callStack;
+  }
+
+  toJSON(): ErrorInfo {
+    return {
+      kind: this.kind,
+      code: this.code,
+      message: this.message,
+      hint: this.hint,
+      span: this.span,
+      callStack: this.callStack,
+    };
+  }
+}
+
+/** Texto legible de un error, como lo muestran el REPL y la consola del sandbox. */
+export const formatError = (error: ErrorInfo): string => {
+  const where = error.span ? ` en la línea ${error.span.start.line}, columna ${error.span.start.column}` : '';
+  const lines = [`Error de ${error.kind}${where}: ${error.message}`];
+  if (error.hint) {
+    lines.push(`Pista: ${error.hint}`);
+  }
+  return lines.join('\n');
+};

package/src/index.ts

@@ -0,0 +1,29 @@
+export { prepare, run, Session } from './engine';
+export type { PreparedProgram, RunOptions, RunResult } from './engine';
+
+export { CodexivoError, formatError } from './errors';
+export type { ErrorInfo, ErrorKind } from './errors';
+
+export { tokenize } from './syntax/lexer';
+export type { LexResult } from './syntax/lexer';
+export { parse } from './syntax/parser';
+export type { ParseResult } from './syntax/parser';
+export { TokenType, KEYWORDS, isKeyword } from './syntax/token';
+export type { Token, Span, Position } from './syntax/token';
+export { childrenOf, walk } from './syntax/ast';
+export type * as ast from './syntax/ast';
+
+export { compile } from './runtime/compiler';
+export type { Chunk, Instruction, DecisionLabel } from './runtime/compiler';
+export { Machine, serialize } from './runtime/machine';
+export type {
+  MachineEvent,
+  MachineOptions,
+  MachineStatus,
+  SerializedValue,
+  Snapshot,
+  FrameSnapshot,
+} 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';

package/src/runtime/builtins.ts

@@ -0,0 +1,133 @@
+import { describeType, isList, repr, show, typeOf, WAIT_FOR_INPUT } from './values';
+import type { NativeContext, NativeValue, Value } from './values';
+
+type NativeFn = (args: Value[], context: NativeContext) => Value | typeof WAIT_FOR_INPUT;
+
+const define = (name: string, arity: NativeValue['arity'], call: NativeFn): NativeValue => ({
+  kind: 'nativo',
+  name,
+  arity,
+  call,
+});
+
+const expectNumber = (name: string, value: Value, context: NativeContext, position = ''): number => {
+  if (typeof value === 'number') return value;
+  throw context.fail(
+    'TIPO_DE_ARGUMENTO',
+    `\`${name}\` espera un número${position}, pero recibió ${describeType(typeOf(value))} (${repr(value)}).`,
+  );
+};
+
+const expectList = (name: string, value: Value, context: NativeContext) => {
+  if (isList(value)) return value;
+  throw context.fail('TIPO_DE_ARGUMENTO', `\`${name}\` espera una lista, pero recibió ${describeType(typeOf(value))}.`);
+};
+
+const numbersOf = (name: string, args: Value[], context: NativeContext): number[] => {
+  const values = args.length === 1 && isList(args[0]!) ? args[0].items : args;
+  if (values.length === 0) {
+    throw context.fail('LISTA_VACÍA', `\`${name}\` necesita al menos un número, pero la lista está vacía.`);
+  }
+  return values.map(value => expectNumber(name, value, context));
+};
+
+const parseNumber = (text: string): number | undefined => {
+  const trimmed = text.trim();
+  if (!/^[-+]?(\d+(\.\d*)?|\.\d+)$/.test(trimmed)) return undefined;
+  return Number(trimmed);
+};
+
+/** Redondeo escolar: los .5 se alejan del cero (2.5 → 3, -2.5 → -3). */
+const roundHalfAway = (value: number, decimals: number): number => {
+  const factor = 10 ** decimals;
+  return (Math.sign(value) * Math.round(Math.abs(value) * factor)) / factor;
+};
+
+const library: NativeValue[] = [
+  // entrada y salida
+  define('imprimir', [0, Infinity], (args, context) => {
+    context.write(`${args.map(show).join(' ')}\n`);
+    return null;
+  }),
+  define('leer', 0, (_args, context) => context.readLine()),
+  define('leer_número', 0, (_args, context) => {
+    const line = context.readLine();
+    if (line === WAIT_FOR_INPUT) return line;
+    if (line === null) throw context.fail('SIN_ENTRADA', '`leer_número` no encontró más datos de entrada.');
+    const value = parseNumber(line);
+    if (value === undefined) {
+      throw context.fail('NO_ES_NÚMERO', `\`leer_número\` esperaba un número, pero leyó ${JSON.stringify(line)}.`);
+    }
+    return value;
+  }),
+
+  // tipos y conversiones
+  define('tipo', 1, args => typeOf(args[0]!)),
+  define('texto', 1, args => show(args[0]!)),
+  define('número', 1, (args, context) => {
+    const value = args[0]!;
+    if (typeof value === 'number') return value;
+    if (typeof value === 'string') {
+      const parsed = parseNumber(value);
+      if (parsed !== undefined) return parsed;
+      throw context.fail('NO_ES_NÚMERO', `No se puede convertir ${JSON.stringify(value)} en número.`);
+    }
+    throw context.fail('TIPO_DE_ARGUMENTO', `No se puede convertir ${describeType(typeOf(value))} en número.`);
+  }),
+  define('longitud', 1, (args, context) => {
+    const value = args[0]!;
+    if (typeof value === 'string') return [...value].length;
+    if (isList(value)) return value.items.length;
+    throw context.fail(
+      'TIPO_DE_ARGUMENTO',
+      `\`longitud\` espera un texto o una lista, pero recibió ${describeType(typeOf(value))}.`,
+    );
+  }),
+
+  // matemáticas
+  define('absoluto', 1, (args, context) => Math.abs(expectNumber('absoluto', args[0]!, context))),
+  define('máximo', [1, Infinity], (args, context) => Math.max(...numbersOf('máximo', args, context))),
+  define('mínimo', [1, Infinity], (args, context) => Math.min(...numbersOf('mínimo', args, context))),
+  define('redondear', [1, 2], (args, context) => {
+    const value = expectNumber('redondear', args[0]!, context);
+    const decimals = args.length > 1 ? expectNumber('redondear', args[1]!, context, ' de decimales') : 0;
+    if (!Number.isInteger(decimals) || decimals < 0) {
+      throw context.fail(
+        'TIPO_DE_ARGUMENTO',
+        'La cantidad de decimales de `redondear` tiene que ser un entero positivo o 0.',
+      );
+    }
+    return roundHalfAway(value, decimals);
+  }),
+
+  // listas
+  define('agregar', 2, (args, context) => {
+    expectList('agregar', args[0]!, context).items.push(args[1]!);
+    return null;
+  }),
+  define('primero', 1, (args, context) => {
+    const list = expectList('primero', args[0]!, context);
+    if (list.items.length === 0) throw context.fail('LISTA_VACÍA', '`primero` no puede tomar nada de una lista vacía.');
+    return list.items[0]!;
+  }),
+  define('último', 1, (args, context) => {
+    const list = expectList('último', args[0]!, context);
+    if (list.items.length === 0) throw context.fail('LISTA_VACÍA', '`último` no puede tomar nada de una lista vacía.');
+    return list.items[list.items.length - 1]!;
+  }),
+];
+
+/** Quita los acentos agudos y la diéresis, pero conserva la ñ. */
+export const withoutAccents = (name: string): string =>
+  name.replace(/[áéíóúü]/g, character => ({ á: 'a', é: 'e', í: 'i', ó: 'o', ú: 'u', ü: 'u' })[character] ?? character);
+
+/** Biblioteca estándar. Cada nombre con acento también se acepta sin él (`máximo` y `maximo`). */
+export const natives: Record<string, NativeValue> = (() => {
+  const table: Record<string, NativeValue> = {};
+  for (const native of library) table[native.name] = native;
+  for (const native of library) {
+    const alias = withoutAccents(native.name);
+    if (!table[alias]) table[alias] = native;
+  }
+  return table;
+})();

package/src/runtime/compiler.ts

@@ -0,0 +1,252 @@
+import type * as ast from '../syntax/ast';
+import type { Value } from './values';
+
+export type DecisionLabel = 'si' | 'pero_si' | 'mientras' | 'hasta_que' | 'para';
+
+/**
+ * Instrucciones de la máquina de Codexivo. Cada una conserva el nodo del AST que la originó, así la
+ * máquina puede decir qué parte del código está ejecutando y dónde ocurrió un error.
+ */
+export type Instruction =
+  /** Inicio de una sentencia: punto natural para pausar. */
+  | { op: 'step'; node: ast.Statement }
+  | { op: 'const'; value: Value; node: ast.Expression }
+  | { op: 'list'; count: number; node: ast.ListLiteral }
+  | { op: 'load'; name: string; node: ast.Identifier; forUpdate?: boolean }
+  /** Saca un valor de la pila y crea la variable en el alcance actual. */
+  | { op: 'declare'; name: string; node: ast.VariableDeclaration }
+  /** Saca un valor de la pila y lo guarda en una variable existente. */
+  | { op: 'store'; name: string; node: ast.Assignment }
+  /** Saca un valor de la pila; es el valor de una sentencia de expresión. */
+  | { op: 'result'; node: ast.ExpressionStatement }
+  | { op: 'unary'; operator: ast.UnaryOperator; node: ast.Unary }
+  | { op: 'binary'; operator: ast.BinaryOperator; node: ast.Binary | ast.Assignment }
+  | { op: 'index'; node: ast.Index }
+  | { op: 'closure'; chunk: Chunk; node: ast.FunctionLiteral }
+  | { op: 'call'; argc: number; node: ast.Call }
+  | { op: 'return'; hasValue: boolean; node: ast.Return }
+  | { op: 'jump'; target: number }
+  /** Saca la condición (debe ser lógica) y salta si vale `jumpWhen`. */
+  | {
+      op: 'branch';
+      target: number;
+      jumpWhen: boolean;
+      label: DecisionLabel;
+      node: ast.Expression;
+      owner: ast.Statement;
+    }
+  /** Cortocircuito: revisa el lado izquierdo de `y`/`o`; si ya decide el resultado, lo deja y salta. */
+  | { op: 'shortCircuit'; target: number; node: ast.Logical }
+  /** Revisa que el lado derecho de `y`/`o` sea lógico. */
+  | { op: 'checkLogical'; node: ast.Logical }
+  | { op: 'enterScope' }
+  | { op: 'exitScope' }
+  | { op: 'halt' };
+
+/** Código de un procedimiento o del programa principal. */
+export interface Chunk {
+  name: string;
+  params: string[];
+  code: Instruction[];
+  node: ast.Program | ast.FunctionLiteral;
+}
+
+/** Traduce el AST a instrucciones. El AST debe venir sin errores de sintaxis. */
+export const compile = (program: ast.Program): Chunk => {
+  const compiler = new Compiler({ name: 'programa', params: [], code: [], node: program });
+  for (const statement of program.statements) compiler.statement(statement);
+  compiler.emit({ op: 'halt' });
+  return compiler.chunk;
+};
+
+const compileFunction = (node: ast.FunctionLiteral): Chunk => {
+  const compiler = new Compiler({
+    name: node.name ?? 'procedimiento',
+    params: node.params.map(param => param.name),
+    code: [],
+    node,
+  });
+  // El cuerpo comparte alcance con los parámetros: así `variable x` dentro de `procedimiento(x)` es un error.
+  for (const statement of node.body.statements) compiler.statement(statement);
+  compiler.emit({ op: 'const', value: null, node });
+  compiler.emit({ op: 'return', hasValue: true, node: { kind: 'Return', id: node.id, span: node.body.span } });
+  return compiler.chunk;
+};
+
+class Compiler {
+  constructor(readonly chunk: Chunk) {}
+
+  emit(instruction: Instruction): number {
+    this.chunk.code.push(instruction);
+    return this.chunk.code.length - 1;
+  }
+
+  private get here(): number {
+    return this.chunk.code.length;
+  }
+
+  private patch(at: number, target: number): void {
+    const instruction = this.chunk.code[at];
+    if (instruction && 'target' in instruction) instruction.target = target;
+  }
+
+  statement(node: ast.Statement): void {
+    if (node.kind !== 'Block') this.emit({ op: 'step', node });
+    switch (node.kind) {
+      case 'VariableDeclaration':
+        this.expression(node.value);
+        this.emit({ op: 'declare', name: node.name.name, node });
+        return;
+      case 'Assignment':
+        if (node.operator !== '=') {
+          this.emit({ op: 'load', name: node.target.name, node: node.target, forUpdate: true });
+        }
+        this.expression(node.value);
+        if (node.operator !== '=') {
+          this.emit({ op: 'binary', operator: node.operator[0] as ast.BinaryOperator, node });
+        }
+        this.emit({ op: 'store', name: node.target.name, node });
+        return;
+      case 'ExpressionStatement':
+        this.expression(node.expression);
+        this.emit({ op: 'result', node });
+        return;
+      case 'Return':
+        if (node.value) this.expression(node.value);
+        this.emit({ op: 'return', hasValue: Boolean(node.value), node });
+        return;
+      case 'Block':
+        this.block(node);
+        return;
+      case 'If': {
+        const exits: number[] = [];
+        node.branches.forEach((branch, index) => {
+          this.expression(branch.condition);
+          const skip = this.emit({
+            op: 'branch',
+            target: -1,
+            jumpWhen: false,
+            label: index === 0 ? 'si' : 'pero_si',
+            node: branch.condition,
+            owner: node,
+          });
+          this.block(branch.body);
+          exits.push(this.emit({ op: 'jump', target: -1 }));
+          this.patch(skip, this.here);
+        });
+        if (node.alternative) this.block(node.alternative);
+        for (const exit of exits) this.patch(exit, this.here);
+        return;
+      }
+      case 'While': {
+        const start = this.here;
+        this.expression(node.condition);
+        const exit = this.emit({
+          op: 'branch',
+          target: -1,
+          jumpWhen: false,
+          label: 'mientras',
+          node: node.condition,
+          owner: node,
+        });
+        this.block(node.body);
+        this.emit({ op: 'jump', target: start });
+        this.patch(exit, this.here);
+        return;
+      }
+      case 'DoUntil': {
+        const start = this.here;
+        this.block(node.body);
+        this.expression(node.condition);
+        this.emit({
+          op: 'branch',
+          target: start,
+          jumpWhen: false,
+          label: 'hasta_que',
+          node: node.condition,
+          owner: node,
+        });
+        return;
+      }
+      case 'For': {
+        this.emit({ op: 'enterScope' });
+        if (node.init) this.statement(node.init);
+        const start = this.here;
+        let exit = -1;
+        if (node.condition) {
+          this.expression(node.condition);
+          exit = this.emit({
+            op: 'branch',
+            target: -1,
+            jumpWhen: false,
+            label: 'para',
+            node: node.condition,
+            owner: node,
+          });
+        }
+        this.block(node.body);
+        if (node.update) this.statement(node.update);
+        this.emit({ op: 'jump', target: start });
+        if (exit >= 0) this.patch(exit, this.here);
+        this.emit({ op: 'exitScope' });
+        return;
+      }
+    }
+  }
+
+  private block(node: ast.Block): void {
+    this.emit({ op: 'enterScope' });
+    for (const statement of node.statements) this.statement(statement);
+    this.emit({ op: 'exitScope' });
+  }
+
+  private expression(node: ast.Expression): void {
+    switch (node.kind) {
+      case 'NumberLiteral':
+      case 'StringLiteral':
+      case 'BooleanLiteral':
+        this.emit({ op: 'const', value: node.value, node });
+        return;
+      case 'NullLiteral':
+        this.emit({ op: 'const', value: null, node });
+        return;
+      case 'ListLiteral':
+        for (const element of node.elements) this.expression(element);
+        this.emit({ op: 'list', count: node.elements.length, node });
+        return;
+      case 'Identifier':
+        this.emit({ op: 'load', name: node.name, node });
+        return;
+      case 'Unary':
+        this.expression(node.operand);
+        this.emit({ op: 'unary', operator: node.operator, node });
+        return;
+      case 'Binary':
+        this.expression(node.left);
+        this.expression(node.right);
+        this.emit({ op: 'binary', operator: node.operator, node });
+        return;
+      case 'Logical': {
+        this.expression(node.left);
+        const skip = this.emit({ op: 'shortCircuit', target: -1, node });
+        this.expression(node.right);
+        this.emit({ op: 'checkLogical', node });
+        this.patch(skip, this.here);
+        return;
+      }
+      case 'Call':
+        this.expression(node.callee);
+        for (const arg of node.args) this.expression(arg);
+        this.emit({ op: 'call', argc: node.args.length, node });
+        return;
+      case 'Index':
+        this.expression(node.object);
+        this.expression(node.index);
+        this.emit({ op: 'index', node });
+        return;
+      case 'FunctionLiteral':
+        this.emit({ op: 'closure', chunk: compileFunction(node), node });
+        return;
+    }
+  }
+}