codexivo 0.0.0-stage → 0.2.3

package/docs/recetario.md

@@ -0,0 +1,159 @@
+# Recetario de programas Codexivo
+
+Esta colección de programas ilustra patrones útiles del lenguaje. Cada ejemplo está listo para copiarse en el REPL o en un
+archivo `.codexivo`.
+
+## 1. Hola mundo personalizado
+
+```codexivo
+variable saludar = procedimiento(nombre) {
+  regresa "Hola " + nombre + "!"
+}
+
+saludar("Codexivo")
+```
+
+Demuestra cómo declarar un procedimiento, concatenar cadenas y retornar un valor.
+
+## 2. Clasificador por edades
+
+```codexivo
+variable clasificar = procedimiento(edad) {
+  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"
+  }
+}
+
+clasificar(16)
+```
+
+Ilustra el encadenamiento `si`/`pero_si`/`si_no` y el uso de operadores relacionales.
+
+## 3. Promedio simple
+
+```codexivo
+variable promedio = procedimiento(a, b, c) {
+  variable total = a + b + c
+  regresa total / 3
+}
+
+promedio(8, 7.5, 9)
+```
+
+Combina números enteros y decimales con operaciones aritméticas.
+
+## 4. Valor absoluto
+
+```codexivo
+variable valorAbsoluto = procedimiento(n) {
+  si (n es_menor_que 0) {
+    regresa -n
+  } si_no {
+    regresa n
+  }
+}
+
+valorAbsoluto(-42)
+```
+
+Ejemplo de uso del operador prefijo `-`.
+
+## 5. Contador recursivo
+
+```codexivo
+variable cuentaRegresiva = procedimiento(n) {
+  si (n es_igual_a 0) {
+    regresa "¡Despegue!"
+  }
+
+  regresa cuentaRegresiva(n - 1)
+}
+
+cuentaRegresiva(3)
+```
+
+Muestra cómo las funciones en Codexivo soportan recursión gracias a que conservan su entorno de definición.
+
+## 6. Validación de longitud
+
+```codexivo
+variable esNombreValido = procedimiento(nombre) {
+  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
+}
+
+esNombreValido("Ana")
+```
+
+Ejemplo de uso del builtin `longitud` junto con operadores de comparación y booleanos.
+
+## 7. Suma con un bucle que cuenta
+
+```codexivo
+procedimiento sumar_hasta(n) {
+  variable suma = 0
+  para i desde 1 hasta n {
+    suma = suma + i
+  }
+  regresa suma
+}
+
+sumar_hasta(10) // Suma de 1 a 10 = 55
+```
+
+Demuestra `para … desde … hasta`, que incluye los dos extremos.
+
+## 8. Búsqueda en arreglo
+
+```codexivo
+procedimiento buscar_posición(lista, elemento) {
+  para_cada i en índices(lista) {
+    si (lista[i] es_igual_a elemento) {
+      regresa i
+    }
+  }
+  regresa -1
+}
+
+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.
+
+## 9. Trabajo con funciones matemáticas
+
+```codexivo
+variable estadisticas = procedimiento(datos) {
+  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 (dato es_menor_que menor) {
+      menor = dato
+    }
+  }
+  variable promedio = suma / longitud(datos)
+
+  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.
+
+Todos los ejemplos de este recetario se ejecutan con la versión actual del intérprete. Consulta [qué funciona hoy](./lenguaje.md)
+y [hacia dónde va el lenguaje](./especificacion-v1.md).

package/docs/repl.md

@@ -0,0 +1,64 @@
+# REPL y ejecución desde la terminal
+
+Instala el principal con `npm install -g codexivo` o `bun add -g --trust codexivo`. El gestor selecciona el paquete nativo
+compatible mediante `os`, `cpu` y `libc`; `postinstall` verifica la versión y coloca el ejecutable en la ruta `bin` del
+principal. Una vez instalado, `codexivo` abre el REPL y `codexivo programa.cdx` ejecuta archivos sin necesitar Node.js ni Bun.
+
+Si omites scripts, la biblioteca sigue disponible; para preparar el CLI tras una instalación local, ejecuta
+`node node_modules/codexivo/postinstall.mjs` una vez. Los ejecutables de
+[Releases](https://github.com/UrielCuriel/codexivo/releases) funcionan directamente sin gestores ni runtimes externos.
+En Linux/macOS, aplica `chmod +x` al ejecutable descargado. Se admiten x64 y ARM64 en Linux, macOS y Windows; para Alpine
+Linux elige la variante `musl`.
+
+## REPL
+
+```sh
+bun install
+bun run repl
+```
+
+Escribe código y presiona Enter. Las variables se conservan entre entradas. Si una línea deja un bloque `{` abierto, el REPL
+sigue leyendo (con el prompt `..`) hasta que lo cierres. Para salir escribe `salir`.
+
+```
+>> variable saludar = procedimiento(nombre) { regresa "Hola, " + nombre; };
+>> saludar("Codexivo")
+"Hola, Codexivo"
+>> si (verdadero) {
+..   imprimir("dentro del bloque")
+.. }
+dentro del bloque
+>> salir
+¡Adiós!
+```
+
+En el REPL se puede volver a declarar una variable (`variable x = …` dos veces) para experimentar; en un programa normal es un
+error.
+
+## Ejecutar un archivo
+
+```sh
+bun run src/cli.ts programa.cdx
+```
+
+Lo que llegue por la entrada estándar alimenta a `leer()` y `leer_número()`:
+
+```sh
+echo 21 | bun run src/cli.ts doble.cdx
+```
+
+## Ver la ejecución desde código
+
+```ts
+import { prepare, run } from 'codexivo';
+
+// Todos los eventos de una ejecución
+const { events } = run('variable x = 1; x += 1;', { trace: true });
+
+// Paso a paso
+const { machine } = prepare('variable x = 1;\nx += 1;');
+while (machine && !machine.done) {
+  machine.step();
+  console.log(machine.snapshot().span?.start.line, machine.snapshot().frames[0]?.scopes);
+}
+```

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "codexivo",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.3",
+  "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": [
+    "dist/index.js",
+    "dist/index.js.map",
+    "dist/worker.js",
+    "dist/worker.js.map",
+    "src",
+    "!src/cli.ts",
+    "docs",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./worker": {
+      "types": "./src/worker.ts",
+      "import": "./dist/worker.js"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "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 ./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"
+  },
+  "keywords": [
+    "lenguaje de programación",
+    "español",
+    "educación",
+    "intérprete"
+  ],
+  "author": "Uriel Curiel",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UrielCuriel/codexivo.git"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.4.3"
+  },
+  "packageManager": "bun@1.4.4",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "workspaces": [
+    "packages/*"
+  ]
+}

package/src/catalog.ts

@@ -0,0 +1,256 @@
+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',
+  '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,
+};

package/src/challenge.ts

@@ -0,0 +1,138 @@
+import { run } from './engine';
+import type { ErrorInfo } from './errors';
+import { equals, repr } from './runtime/values';
+import type { DictKey, Value } from './runtime/values';
+
+/**
+ * Retos: un conjunto de casos que se ejecutan con su propia entrada y su propio límite de operaciones. Corre
+ * igual en el worker del sitio y en Bun, así los retos se prueban en CI.
+ *
+ * - Estilo `salida` (como HackerRank): el programa lee con `leer()` y se compara lo que imprime.
+ * - Estilo `regresa` (como LeetCode): se llama a `resolver(…)` (u otro procedimiento) con argumentos y se compara
+ *   lo que regresa, por valor.
+ */
+
+/** Un valor de JSON: los arreglos se vuelven listas y los objetos, diccionarios. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+
+export interface ChallengeCase {
+  name?: string;
+  /** Entrada estándar: un texto (una línea por renglón) o una lista de líneas. */
+  input?: string | string[];
+  /** Estilo `salida`: lo que el programa tiene que imprimir. */
+  expectedOutput?: string;
+  /** Estilo `regresa`: los argumentos para el procedimiento. */
+  args?: JsonValue[];
+  /** Estilo `regresa`: lo que tiene que regresar. */
+  expected?: JsonValue;
+  /** Límite de operaciones de este caso; si no, el del reto. */
+  maxOperations?: number;
+}
+
+export interface Challenge {
+  style: 'salida' | 'regresa';
+  cases: ChallengeCase[];
+  /** Estilo `regresa`: el procedimiento que se llama. Por defecto `resolver`. */
+  procedure?: string;
+  /** Límite de operaciones por caso. Por defecto 1 000 000. */
+  maxOperations?: number;
+  /**
+   * Con `true`, la salida tiene que ser idéntica. Si no, se ignoran los espacios al final de cada línea y las
+   * líneas vacías del final.
+   */
+  exactOutput?: boolean;
+}
+
+export interface CaseResult {
+  name: string;
+  passed: boolean;
+  output: string;
+  expectedOutput?: string;
+  /** Estilo `regresa`: lo que regresó y lo que se esperaba, como se escribirían en código. */
+  result?: string;
+  expected?: string;
+  operations: number;
+  error?: ErrorInfo;
+}
+
+export interface ChallengeResult {
+  passed: boolean;
+  cases: CaseResult[];
+}
+
+const DEFAULT_MAX_OPERATIONS = 1_000_000;
+
+/** Un valor de JSON escrito como literal de Codexivo. */
+const literal = (value: JsonValue): string => {
+  if (value === null) return 'nulo';
+  if (typeof value === 'boolean') return value ? 'verdadero' : 'falso';
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error(`El reto tiene un número que no es finito: ${value}.`);
+    return value < 0 ? `(${value})` : String(value);
+  }
+  if (typeof value === 'string') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(literal).join(', ')}]`;
+  return `{ ${Object.entries(value)
+    .map(([key, item]) => `${JSON.stringify(key)}: ${literal(item)}`)
+    .join(', ')} }`;
+};
+
+/** Un valor de JSON como valor de Codexivo, para comparar por valor con `equals`. */
+const toValue = (value: JsonValue): Value => {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return { kind: 'lista', id: 0, items: value.map(toValue) };
+  return {
+    kind: 'diccionario',
+    id: 0,
+    entries: new Map<DictKey, Value>(Object.entries(value).map(([key, item]) => [key, toValue(item)])),
+  };
+};
+
+const normalize = (text: string): string =>
+  text
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map(line => line.replace(/[ \t]+$/, ''))
+    .join('\n')
+    .replace(/\n+$/, '');
+
+/** Ejecuta cada caso del reto con el código de quien lo resuelve. */
+export const evaluarReto = (source: string, challenge: Challenge): ChallengeResult => {
+  const procedure = challenge.procedure ?? 'resolver';
+  const cases = challenge.cases.map((testCase, index): CaseResult => {
+    const name = testCase.name ?? `Caso ${index + 1}`;
+    const maxOperations = testCase.maxOperations ?? challenge.maxOperations ?? DEFAULT_MAX_OPERATIONS;
+    const input = testCase.input ?? [];
+
+    if (challenge.style === 'salida') {
+      const result = run(source, { input, maxOperations });
+      const expectedOutput = testCase.expectedOutput ?? '';
+      const same = challenge.exactOutput
+        ? result.output === expectedOutput
+        : normalize(result.output) === normalize(expectedOutput);
+      return {
+        name,
+        passed: result.ok && same,
+        output: result.output,
+        expectedOutput,
+        operations: result.operations,
+        ...(result.errors[0] ? { error: result.errors[0] } : {}),
+      };
+    }
+
+    // La llamada va al final, en su propia línea, para que los errores del programa conserven su lugar.
+    const call = `\n;\nregresa ${procedure}(${(testCase.args ?? []).map(literal).join(', ')});\n`;
+    const result = run(source + call, { input, maxOperations });
+    const expected = toValue(testCase.expected ?? null);
+    return {
+      name,
+      passed: result.ok && equals(result.result, expected),
+      output: result.output,
+      result: result.resultText,
+      expected: repr(expected),
+      operations: result.operations,
+      ...(result.errors[0] ? { error: result.errors[0] } : {}),
+    };
+  });
+  return { passed: cases.every(testCase => testCase.passed), cases };
+};