codexivo 0.2.0 → 1.0.0

package/docs/modo-mundo.md

@@ -0,0 +1,128 @@
+# Modo mundo
+
+Codexivo nació de querer algo como el robot Karel. El **modo mundo** es el mismo lenguaje con procedimientos extra para
+mover un robot en una cuadrícula. Este repositorio define el mundo, sus reglas y sus eventos; el sitio lo dibuja.
+
+## El mundo
+
+Un mundo se describe en JSON (formato versión 1):
+
+```json
+{
+  "version": 1,
+  "width": 5,
+  "height": 1,
+  "walls": [],
+  "beepers": [
+    { "x": 2, "y": 1, "count": 1 },
+    { "x": 4, "y": 1, "count": 3 }
+  ],
+  "robot": { "x": 1, "y": 1, "facing": "este", "beepers": 0 }
+}
+```
+
+| Campo             | Qué es                                                                                                               |
+| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `version`         | Siempre `1`                                                                                                          |
+| `width`, `height` | Casillas de oeste a este y de sur a norte (de 1 a 100). La casilla suroeste es `(1, 1)`                              |
+| `walls`           | Paredes: `{ "x", "y", "side" }` es la pared del lado `side` (`"norte"`, `"este"`, `"sur"`, `"oeste"`) de esa casilla |
+| `beepers`         | Zumbadores por casilla: `{ "x", "y", "count" }`, con `count` un entero o `"infinito"`                                |
+| `robot`           | Posición, orientación (`facing`) y zumbadores en la mochila (`beepers`, entero o `"infinito"`)                       |
+
+Los bordes de la cuadrícula siempre son paredes. `validateWorld(json)` revisa un mundo y regresa los problemas con su
+ubicación (`robot.x`, `walls[2].side`…) para mostrarlos en el editor.
+
+## Los procedimientos
+
+Solo existen cuando el programa corre en un mundo.
+
+| Acción               | Qué hace                                       |
+| -------------------- | ---------------------------------------------- |
+| `avanzar()`          | Avanza una casilla hacia donde mira            |
+| `girar_izquierda()`  | Gira 90° a la izquierda                        |
+| `recoger_zumbador()` | Toma un zumbador de la casilla y lo guarda     |
+| `dejar_zumbador()`   | Deja un zumbador de la mochila en la casilla   |
+| `apagar()`           | Apaga el robot; después ya no puede hacer nada |
+
+| Pregunta                                                                            | Responde `verdadero` si…               |
+| ----------------------------------------------------------------------------------- | -------------------------------------- |
+| `frente_libre()`, `izquierda_libre()`, `derecha_libre()`                            | No hay pared en esa dirección          |
+| `hay_zumbador()`                                                                    | Hay al menos un zumbador en la casilla |
+| `tengo_zumbadores()`                                                                | Hay al menos un zumbador en la mochila |
+| `mirando_al_norte()`, `mirando_al_sur()`, `mirando_al_este()`, `mirando_al_oeste()` | El robot mira hacia ese lado           |
+
+No hay `girar_derecha()`: construirlo es el primer ejercicio.
+
+## Un ejemplo
+
+Recoger todos los zumbadores de la fila y volver al inicio:
+
+```codexivo
+procedimiento girar_derecha() {
+  repetir 3 veces {
+    girar_izquierda()
+  }
+}
+
+procedimiento recoger_todos() {
+  mientras (hay_zumbador()) {
+    recoger_zumbador()
+  }
+}
+
+mientras (frente_libre()) {
+  avanzar()
+  recoger_todos()
+}
+
+// media vuelta y de regreso
+girar_derecha()
+girar_derecha()
+mientras (frente_libre()) {
+  avanzar()
+}
+apagar()
+```
+
+Al terminar, el robot está en `(1, 1)` mirando al oeste, apagado y con los 4 zumbadores en la mochila.
+
+## Errores
+
+Son errores de ejecución que dicen dónde está y hacia dónde mira el robot:
+
+| Código             | Cuándo                                          |
+| ------------------ | ----------------------------------------------- |
+| `CHOQUE_CON_PARED` | `avanzar()` contra una pared o el borde         |
+| `SIN_ZUMBADORES`   | `recoger_zumbador()` donde no hay               |
+| `MOCHILA_VACÍA`    | `dejar_zumbador()` sin zumbadores en la mochila |
+| `ROBOT_APAGADO`    | Cualquier acción después de `apagar()`          |
+
+```
+Error de ejecución en la línea 3, columna 1: El robot chocó con una pared. El robot está en (2, 1) mirando al este.
+Pista: Pregunta antes con `frente_libre()`.
+```
+
+## Desde JavaScript
+
+```ts
+import { checkGoal, createWorld, run } from 'codexivo';
+
+const world = createWorld(definición);
+const result = run(código, { world, trace: true });
+
+result.world; // estado final: el mismo formato del mundo, más `robot.on`
+result.events?.filter(event => event.type === 'robot'); // una por acción: before, after y la casilla
+
+checkGoal(result.world!, {
+  robot: { x: 1, y: 1, on: false },
+  beepers: [],
+  onlyListedBeepers: true, // las casillas no listadas tienen que quedar vacías
+});
+// → { ok: true, differences: [] }
+```
+
+- Cada acción emite un evento `robot` con `action`, el robot `before` y `after` (posición, orientación, mochila y si
+  está encendido) y, al recoger o dejar, los zumbadores que quedaron en la casilla (`cell`).
+- `machine.snapshot().world` trae el estado del mundo en cualquier pausa.
+- `checkGoal` compara el mundo final con un objetivo y solo revisa lo que el objetivo indica; cada diferencia trae un
+  mensaje para mostrarlo en el reto.

package/docs/recetario.md

@@ -7,10 +7,10 @@ archivo `.codexivo`.
 
 ```codexivo
 variable saludar = procedimiento(nombre) {
-  regresa "Hola " + nombre + "!";
-};
+  regresa "Hola " + nombre + "!"
+}
 
-saludar("Codexivo");
+saludar("Codexivo")
 ```
 
 Demuestra cómo declarar un procedimiento, concatenar cadenas y retornar un valor.
@@ -19,16 +19,16 @@ Demuestra cómo declarar un procedimiento, concatenar cadenas y retornar un valo
 
 ```codexivo
 variable clasificar = procedimiento(edad) {
-  si (edad >= 18) {
-    regresa "adulto";
-  } pero_si (edad >= 13) {
-    regresa "adolescente";
+  si (edad es_mayor_o_igual_a 18) {
+    regresa "adulto"
+  } pero_si (edad es_mayor_o_igual_a 13) {
+    regresa "adolescente"
   } si_no {
-    regresa "niño";
+    regresa "niño"
   }
-};
+}
 
-clasificar(16);
+clasificar(16)
 ```
 
 Ilustra el encadenamiento `si`/`pero_si`/`si_no` y el uso de operadores relacionales.
@@ -37,11 +37,11 @@ Ilustra el encadenamiento `si`/`pero_si`/`si_no` y el uso de operadores relacion
 
 ```codexivo
 variable promedio = procedimiento(a, b, c) {
-  variable total = a + b + c;
-  regresa total / 3;
-};
+  variable total = a + b + c
+  regresa total / 3
+}
 
-promedio(8, 7.5, 9);
+promedio(8, 7.5, 9)
 ```
 
 Combina números enteros y decimales con operaciones aritméticas.
@@ -50,30 +50,30 @@ Combina números enteros y decimales con operaciones aritméticas.
 
 ```codexivo
 variable valorAbsoluto = procedimiento(n) {
-  si (n < 0) {
-    regresa -n;
+  si (n es_menor_que 0) {
+    regresa -n
   } si_no {
-    regresa n;
+    regresa n
   }
-};
+}
 
-valorAbsoluto(-42);
+valorAbsoluto(-42)
 ```
 
-Ejemplo de uso del operador prefijo `-` y del comportamiento truthy/falsy en condicionales.
+Ejemplo de uso del operador prefijo `-`.
 
 ## 5. Contador recursivo
 
 ```codexivo
 variable cuentaRegresiva = procedimiento(n) {
-  si (n == 0) {
-    regresa "¡Despegue!";
+  si (n es_igual_a 0) {
+    regresa "¡Despegue!"
   }
 
-  regresa cuentaRegresiva(n - 1);
-};
+  regresa cuentaRegresiva(n - 1)
+}
 
-cuentaRegresiva(3);
+cuentaRegresiva(3)
 ```
 
 Muestra cómo las funciones en Codexivo soportan recursión gracias a que conservan su entorno de definición.
@@ -82,48 +82,48 @@ Muestra cómo las funciones en Codexivo soportan recursión gracias a que conser
 
 ```codexivo
 variable esNombreValido = procedimiento(nombre) {
-  variable tamaño = longitud(nombre);
-  si (tamaño >= 3 y tamaño <= 15) {
-    regresa verdadero;
+  variable tamaño = longitud(nombre)
+  si (tamaño es_mayor_o_igual_a 3 y tamaño es_menor_o_igual_a 15) {
+    regresa verdadero
   }
-  regresa falso;
-};
+  regresa falso
+}
 
-esNombreValido("Ana");
+esNombreValido("Ana")
 ```
 
 Ejemplo de uso del builtin `longitud` junto con operadores de comparación y booleanos.
 
-## 7. Suma con bucle for
+## 7. Suma con un bucle que cuenta
 
 ```codexivo
-variable sumarHasta = procedimiento(n) {
-  variable suma = 0;
-  para (variable i = 1; i <= n; i += 1) {
-    suma += i;
+procedimiento sumar_hasta(n) {
+  variable suma = 0
+  para i desde 1 hasta n {
+    suma = suma + i
   }
-  regresa suma;
-};
+  regresa suma
+}
 
-sumarHasta(10); // Suma de 1 a 10 = 55
+sumar_hasta(10) // Suma de 1 a 10 = 55
 ```
 
-Demuestra el uso de bucles `para` con operadores de asignación compuesta.
+Demuestra `para … desde … hasta`, que incluye los dos extremos.
 
 ## 8. Búsqueda en arreglo
 
 ```codexivo
-variable buscar = procedimiento(arreglo, elemento) {
-  para (variable i = 0; i < longitud(arreglo); i += 1) {
-    si (arreglo[i] == elemento) {
-      regresa i;
+procedimiento buscar_posición(lista, elemento) {
+  para_cada i en índices(lista) {
+    si (lista[i] es_igual_a elemento) {
+      regresa i
     }
   }
-  regresa -1;
-};
+  regresa -1
+}
 
-variable numeros = [10, 20, 30, 40];
-buscar(numeros, 30); // Regresa 2
+variable números = [10, 20, 30, 40]
+buscar_posición(números, 30) // Regresa 2
 ```
 
 Combina bucles, acceso a arreglos, condicionales y funciones built-in.
@@ -132,25 +132,25 @@ Combina bucles, acceso a arreglos, condicionales y funciones built-in.
 
 ```codexivo
 variable estadisticas = procedimiento(datos) {
-  variable suma = 0;
-  variable mayor = primero(datos);
-  variable menor = primero(datos);
-  
-  para (variable i = 0; i < longitud(datos); i += 1) {
-    suma += datos[i];
-    si (datos[i] > mayor) {
-      mayor = datos[i];
+  variable suma = 0
+  variable mayor = primero(datos)
+  variable menor = primero(datos)
+
+  para_cada dato en datos {
+    suma = suma + dato
+    si (dato es_mayor_que mayor) {
+      mayor = dato
     }
-    si (datos[i] < menor) {
-      menor = datos[i];
+    si (dato es_menor_que menor) {
+      menor = dato
     }
   }
-  variable promedio = suma / longitud(datos);
-  
-  regresa [redondear(promedio), mayor, menor];
-};
+  variable promedio = suma / longitud(datos)
 
-estadisticas([5, 2, 8, 1, 9]); // [5, 9, 1]
+  regresa [redondear(promedio), mayor, menor]
+}
+
+estadisticas([5, 2, 8, 1, 9])  // [5, 9, 1]
 ```
 
 Muestra el uso de las funciones matemáticas built-in y manipulación de arreglos.

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "codexivo",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "Lenguaje de programación en español para practicar lógica y algoritmos, que se ejecuta en el navegador.",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "src/index.ts",
   "files": [
-    "bin/codexivo.exe",
-    "postinstall.mjs",
     "dist/index.js",
     "dist/index.js.map",
+    "dist/worker.js",
+    "dist/worker.js.map",
     "src",
     "!src/cli.ts",
     "docs",
@@ -20,6 +20,10 @@
     ".": {
       "types": "./src/index.ts",
       "import": "./dist/index.js"
+    },
+    "./worker": {
+      "types": "./src/worker.ts",
+      "import": "./dist/worker.js"
     }
   },
   "scripts": {
@@ -27,16 +31,16 @@
     "check": "bun check",
     "repl": "bun run src/cli.ts",
     "build": "bun run build:lib && bun run build:binary",
-    "build:lib": "bun build ./src/index.ts --target browser --format esm --outdir=dist --minify --sourcemap=linked",
+    "build:lib": "bun build ./src/index.ts ./src/worker.ts --target browser --format esm --outdir=dist --minify --sourcemap=linked",
     "build:binary": "bun run scripts/build-binaries.ts",
     "build:binaries": "bun run scripts/build-binaries.ts --all",
     "test:package": "bun run scripts/test-package.ts",
+    "docs:biblioteca": "bun run scripts/docs-biblioteca.ts",
     "prepack": "bun run build:lib",
     "version": "bun run scripts/sync-native-versions.ts && git add package.json bun.lock packages/*/package.json",
     "publish:native": "bun run scripts/publish-native.ts",
     "format": "bun fmt",
-    "format:check": "bun fmt --check",
-    "postinstall": "node ./postinstall.mjs"
+    "format:check": "bun fmt --check"
   },
   "keywords": [
     "lenguaje de programación",
@@ -60,18 +64,5 @@
   },
   "workspaces": [
     "packages/*"
-  ],
-  "optionalDependencies": {
-    "codexivo-linux-x64": "0.2.0",
-    "codexivo-linux-x64-musl": "0.2.0",
-    "codexivo-linux-arm64": "0.2.0",
-    "codexivo-linux-arm64-musl": "0.2.0",
-    "codexivo-darwin-x64": "0.2.0",
-    "codexivo-darwin-arm64": "0.2.0",
-    "codexivo-windows-x64": "0.2.0",
-    "codexivo-windows-arm64": "0.2.0"
-  },
-  "bin": {
-    "codexivo": "./bin/codexivo.exe"
-  }
+  ]
 }

package/src/catalog.ts

@@ -0,0 +1,257 @@
+import { ERROR_CODES } from './error-codes';
+import type { ErrorKind } from './errors';
+import { constantDocs, constants, natives, withoutAccents } from './runtime/builtins';
+import { libraryDocs } from './runtime/prelude';
+import type { ProcedureCategory, ProcedureDoc, ProcedureLevel } from './runtime/values';
+import { KEYWORDS, TokenType } from './syntax/token';
+import { EXAMPLE_WORLD, worldDocs } from './world';
+import type { WorldDefinition } from './world';
+
+/**
+ * El lenguaje y su biblioteca como datos, para que el resaltado, el autocompletado, la documentación y los
+ * avisos del editor del sitio salgan de una sola fuente. Todo es serializable: no hay funciones.
+ */
+
+export type KeywordGroup = 'declaración' | 'control' | 'lógicas' | 'literales' | 'operadores';
+
+export interface OperatorEntry {
+  symbol?: string;
+  /** Forma en palabras (`es_igual_a`, `mod`), si la tiene. */
+  word?: string;
+  /** Nivel de precedencia de la §4.1: 1 es el que agrupa al final, 9 el primero. */
+  precedence: number;
+  associativity: 'izquierda' | 'derecha' | 'prefijo' | 'sin encadenar';
+  description: string;
+}
+
+export interface ProcedureEntry extends ProcedureDoc {
+  /** Nombre canónico, con acento si lo lleva. */
+  name: string;
+  /** Otras formas aceptadas (el nombre sin acento). */
+  aliases: string[];
+}
+
+export interface ConstantEntry {
+  name: string;
+  value: number;
+  level: ProcedureLevel;
+  description: string;
+}
+
+export interface ErrorEntry {
+  code: string;
+  kind: ErrorKind;
+  explanation: string;
+}
+
+export interface Catalog {
+  version: 1;
+  keywords: Array<{ group: KeywordGroup; words: string[] }>;
+  operators: OperatorEntry[];
+  /** Procedimientos de la biblioteca, incluidos los del modo mundo (categoría `mundo`). */
+  library: ProcedureEntry[];
+  constants: ConstantEntry[];
+  errors: ErrorEntry[];
+  categories: ProcedureCategory[];
+  /** Mundo con el que se ejecutan los ejemplos de la categoría `mundo`. */
+  exampleWorld: WorldDefinition;
+}
+
+const KEYWORD_GROUPS: Readonly<Record<string, KeywordGroup>> = {
+  [TokenType.LET]: 'declaración',
+  [TokenType.CONST]: 'declaración',
+  [TokenType.DOMAIN]: 'declaración',
+  [TokenType.FUNCTION]: 'declaración',
+  [TokenType.RETURN]: 'declaración',
+  [TokenType.IF]: 'control',
+  [TokenType.ELSEIF]: 'control',
+  [TokenType.ELSE]: 'control',
+  [TokenType.WHILE]: 'control',
+  [TokenType.DO]: 'control',
+  [TokenType.UNTIL]: 'control',
+  [TokenType.FOR]: 'control',
+  [TokenType.FOR_EACH]: 'control',
+  [TokenType.FROM]: 'control',
+  [TokenType.TO]: 'control',
+  [TokenType.STEP]: 'control',
+  [TokenType.IN]: 'control',
+  [TokenType.REPEAT]: 'control',
+  [TokenType.TIMES]: 'control',
+  [TokenType.BREAK]: 'control',
+  [TokenType.CONTINUE]: 'control',
+  [TokenType.AND]: 'lógicas',
+  [TokenType.OR]: 'lógicas',
+  [TokenType.NOT]: 'lógicas',
+  [TokenType.TRUE]: 'literales',
+  [TokenType.FALSE]: 'literales',
+  [TokenType.NULL]: 'literales',
+  [TokenType.MOD]: 'operadores',
+  [TokenType.DIV]: 'operadores',
+  [TokenType.EQ]: 'operadores',
+  [TokenType.NEQ]: 'operadores',
+  [TokenType.LT]: 'operadores',
+  [TokenType.GT]: 'operadores',
+  [TokenType.LTE]: 'operadores',
+  [TokenType.GTE]: 'operadores',
+};
+
+const GROUP_ORDER: KeywordGroup[] = ['declaración', 'control', 'lógicas', 'literales', 'operadores'];
+
+/** Grupo de cada palabra reservada; una palabra sin grupo es un error del catálogo (lo revisa una prueba). */
+export const keywordGroup = (word: string): KeywordGroup | undefined => KEYWORD_GROUPS[KEYWORDS[word] ?? ''];
+
+const keywords = GROUP_ORDER.map(group => ({
+  group,
+  words: Object.keys(KEYWORDS).filter(word => keywordGroup(word) === group),
+}));
+
+const operators: OperatorEntry[] = [
+  {
+    word: 'o',
+    precedence: 1,
+    associativity: 'izquierda',
+    description: 'Verdadero si alguno de los dos lo es. Si el izquierdo es verdadero, no evalúa el derecho.',
+  },
+  {
+    word: 'y',
+    precedence: 2,
+    associativity: 'izquierda',
+    description: 'Verdadero si los dos lo son. Si el izquierdo es falso, no evalúa el derecho.',
+  },
+  {
+    symbol: '!',
+    word: 'no',
+    precedence: 3,
+    associativity: 'prefijo',
+    description: 'Cambia verdadero por falso y al revés.',
+  },
+  {
+    symbol: '==',
+    word: 'es_igual_a',
+    precedence: 4,
+    associativity: 'sin encadenar',
+    description: 'Igualdad por valor, también de listas y diccionarios.',
+  },
+  {
+    symbol: '!=',
+    word: 'es_distinto_de',
+    precedence: 4,
+    associativity: 'sin encadenar',
+    description: 'Lo contrario de `==`.',
+  },
+  {
+    symbol: '<',
+    word: 'es_menor_que',
+    precedence: 4,
+    associativity: 'sin encadenar',
+    description: 'Compara dos números o dos textos.',
+  },
+  {
+    symbol: '>',
+    word: 'es_mayor_que',
+    precedence: 4,
+    associativity: 'sin encadenar',
+    description: 'Compara dos números o dos textos.',
+  },
+  {
+    symbol: '<=',
+    word: 'es_menor_o_igual_a',
+    precedence: 4,
+    associativity: 'sin encadenar',
+    description: 'Compara dos números o dos textos.',
+  },
+  {
+    symbol: '>=',
+    word: 'es_mayor_o_igual_a',
+    precedence: 4,
+    associativity: 'sin encadenar',
+    description: 'Compara dos números o dos textos.',
+  },
+  {
+    symbol: '+',
+    precedence: 5,
+    associativity: 'izquierda',
+    description: 'Suma dos números o une dos textos; no los mezcla.',
+  },
+  { symbol: '-', precedence: 5, associativity: 'izquierda', description: 'Resta.' },
+  { symbol: '*', precedence: 6, associativity: 'izquierda', description: 'Multiplica.' },
+  { symbol: '/', precedence: 6, associativity: 'izquierda', description: 'División real: `7 / 2` es `3.5`.' },
+  {
+    word: 'div',
+    precedence: 6,
+    associativity: 'izquierda',
+    description: 'División entera hacia abajo: `-7 div 2` es `-4`.',
+  },
+  {
+    symbol: '%',
+    word: 'mod',
+    precedence: 6,
+    associativity: 'izquierda',
+    description: 'Residuo consistente con `div`: `-7 mod 3` es `2`.',
+  },
+  { symbol: '-', precedence: 7, associativity: 'prefijo', description: 'Cambia el signo.' },
+  {
+    symbol: '^',
+    precedence: 8,
+    associativity: 'derecha',
+    description: 'Potencia: `2 ^ 3 ^ 2` es `2 ^ 9`, y `-2 ^ 2` es `-4`.',
+  },
+  { symbol: '( )', precedence: 9, associativity: 'izquierda', description: 'Llama a un procedimiento: `f(x)`.' },
+  {
+    symbol: '[ ]',
+    precedence: 9,
+    associativity: 'izquierda',
+    description: 'Elemento de una lista o texto, o clave de un diccionario: `l[0]`, `d["a"]`.',
+  },
+  {
+    symbol: '.',
+    precedence: 9,
+    associativity: 'izquierda',
+    description: 'Campo de un diccionario: `persona.edad` es `persona["edad"]`.',
+  },
+];
+
+const entry = (name: string, doc: ProcedureDoc): ProcedureEntry => {
+  const alias = withoutAccents(name);
+  return { name, aliases: alias === name ? [] : [alias], ...doc };
+};
+
+const library: ProcedureEntry[] = [
+  ...Object.values(natives)
+    .filter((native, index, all) => all.indexOf(native) === index)
+    .map(native => entry(native.name, native.doc!)),
+  ...Object.entries(libraryDocs).map(([name, doc]) => entry(name, doc)),
+  ...Object.entries(worldDocs).map(([name, doc]) => entry(name, doc)),
+];
+
+const CATEGORIES: ProcedureCategory[] = [
+  'entrada y salida',
+  'tipos',
+  'verificación',
+  'matemáticas',
+  'texto',
+  'listas',
+  'diccionarios',
+  'procedimientos',
+  'estructuras',
+  'mundo',
+];
+
+export const catalog: Catalog = {
+  version: 1,
+  keywords,
+  operators,
+  library: library.sort(
+    (a, b) => CATEGORIES.indexOf(a.category) - CATEGORIES.indexOf(b.category) || a.name.localeCompare(b.name, 'es'),
+  ),
+  constants: Object.entries(constantDocs).map(([name, doc]) => ({
+    name,
+    value: constants[name] as number,
+    ...doc,
+  })),
+  errors: Object.entries(ERROR_CODES)
+    .map(([code, info]) => ({ code, ...info }))
+    .sort((a, b) => a.code.localeCompare(b.code, 'es')),
+  categories: CATEGORIES,
+  exampleWorld: EXAMPLE_WORLD,
+};