codexivo 0.2.3 → 1.0.0

package/docs/especificacion-v1.md

@@ -1,7 +1,7 @@
 # Codexivo v1 — Especificación del lenguaje
 
-> **Estado:** aprobada. Se implementa por pasos (§16). Lo que ya funciona está en
-> [`lenguaje.md`](./lenguaje.md), y todos sus ejemplos se prueban automáticamente.
+> **Estado:** implementada en la versión 1.0.0 (§16). Lo que funciona está en [`lenguaje.md`](./lenguaje.md), y todos sus
+> ejemplos se prueban automáticamente.
 >
 > Las secciones marcadas con **✅ Decidido** fueron decisiones abiertas que ya se resolvieron.
 
@@ -429,24 +429,26 @@ calculadora.suma(1, 3); // 4
 
 ## 7. Errores
 
-Cada error es un objeto, no solo un texto:
+Cada error es un objeto, no solo un texto. Los campos de la API van en inglés, como el resto (`kind`, `span`); todo lo que
+lee quien aprende va en español:
 
 ```ts
 {
-  tipo: "léxico" | "sintaxis" | "ejecución" | "límite",
-  código: "DIVISIÓN_ENTRE_CERO",
-  mensaje: "No se puede dividir entre cero.",
-  pista: "Revisa que `divisor` no valga 0 antes de dividir.",
-  inicio: { línea: 4, columna: 12 },
-  fin: { línea: 4, columna: 23 },
-  pila: ["programa", "promedio(lista)"]
+  kind: "léxico" | "sintaxis" | "ejecución" | "límite",
+  code: "DIVISIÓN_ENTRE_CERO",
+  message: "No se puede dividir entre cero.",
+  hint: "Revisa que `divisor` no valga 0 antes de dividir.",
+  span: { start: { line: 4, column: 12, offset: 80 }, end: { line: 4, column: 23, offset: 91 } },
+  callStack: ["programa", "promedio"]
 }
 ```
 
+Cada `code` tiene una explicación larga en el catálogo (`catalog.errors`).
+
 - Los mensajes dicen **qué pasó** y la pista **qué revisar**, en español correcto y con acentos.
 - El parser se recupera y reporta varios errores, pero el sandbox destaca el primero.
-- `afirmar(condición, mensaje)` detiene el programa si la condición es falsa. Es la herramienta más
-  directa para practicar verificación.
+- `afirmar(condición, mensaje)` detiene el programa con `AFIRMACIÓN_FALLIDA` si la condición es falsa; el mensaje
+  es opcional. Es la herramienta más directa para practicar verificación.
 - Sin `intentar`/`capturar` en v1: un error detiene el programa, y eso es lo que queremos que se vea.
 
 ## 8. Biblioteca estándar
@@ -655,13 +657,16 @@ estáticos y `según`/`caso`. Se pueden reconsiderar después, siempre con el pr
 
 Codexivo no tiene usuarios todavía, así que v1 se permite romper compatibilidad:
 
-- condiciones estrictas (si se aprueba §4.5);
+- condiciones estrictas (§4.5);
 - error al llamar con un número distinto de argumentos;
 - error al redeclarar o al asignar sin declarar;
 - `agregar` pasa a modificar la lista (antes regresaba una nueva);
 - un procedimiento sin `regresa` regresa `nulo` (antes regresaba el valor de su última expresión);
 - `1 / 0` pasa a ser error;
-- `ARREGLO` pasa a llamarse `lista` en mensajes y en `tipo()`.
+- `ARREGLO` pasa a llamarse `lista` en mensajes y en `tipo()`;
+- palabras reservadas nuevas (§2.5): `constante`, `dominio`, `repetir`, `veces`, `desde`, `hasta`, `con_paso`,
+  `para_cada`, `en`, `romper`, `continuar`, `mod`, `div` y las comparaciones en palabras ya no sirven como nombres;
+- sin `;`, el salto de línea termina la expresión (§2.4): una expresión partida antes de un operador es un error.
 
 ## 15. Decisiones
 

package/docs/lenguaje.md

@@ -381,14 +381,15 @@ Todo está disponible sin importar nada. Los nombres con acento también se acep
 
 ### Entrada, salida y tipos
 
-| Procedimiento           | Qué hace                                                                                                 |
-| ----------------------- | -------------------------------------------------------------------------------------------------------- |
-| `imprimir(a, b, …)`     | Escribe los valores separados por un espacio y termina la línea                                          |
-| `leer()`                | Siguiente línea de entrada como texto, o `nulo` si ya no hay                                             |
-| `leer_número()`         | Siguiente línea de entrada como número                                                                   |
-| `tipo(x)`               | `"número"`, `"texto"`, `"lógico"`, `"nulo"`, `"lista"`, `"diccionario"`, `"dominio"` o `"procedimiento"` |
-| `texto(x)`, `número(x)` | Conversiones explícitas                                                                                  |
-| `longitud(x)`           | Caracteres de un texto, elementos de una lista o claves de un diccionario                                |
+| Procedimiento                  | Qué hace                                                                                                 |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| `imprimir(a, b, …)`            | Escribe los valores separados por un espacio y termina la línea                                          |
+| `leer()`                       | Siguiente línea de entrada como texto, o `nulo` si ya no hay                                             |
+| `leer_número()`                | Siguiente línea de entrada como número                                                                   |
+| `tipo(x)`                      | `"número"`, `"texto"`, `"lógico"`, `"nulo"`, `"lista"`, `"diccionario"`, `"dominio"` o `"procedimiento"` |
+| `texto(x)`, `número(x)`        | Conversiones explícitas                                                                                  |
+| `longitud(x)`                  | Caracteres de un texto, elementos de una lista o claves de un diccionario                                |
+| `afirmar(condición, mensaje?)` | Detiene el programa si la condición es falsa (ver [Errores](#errores))                                   |
 
 ### Matemáticas
 
@@ -493,6 +494,19 @@ Error de ejecución en la línea 2, columna 5: No se puede dividir entre cero.
 Pista: Revisa que el divisor no valga 0 antes de dividir.
 ```
 
+Con `afirmar` se escribe lo que se espera que sea cierto. Si no lo es, el programa se detiene en esa línea, antes de que el
+error llegue más lejos:
+
+```codexivo
+variable precio = 120
+variable descuento = 20
+variable total = precio - descuento
+afirmar(total es_menor_que precio, "el descuento tenía que bajar el precio")
+imprimir("Total:", total)
+```
+
+Un error detiene el programa: no hay forma de atraparlo y seguir, porque lo que se busca es verlo.
+
 ## Puente hacia otros lenguajes
 
 Muchos lenguajes (C, Java, JavaScript) cuentan con un `for` de tres partes. Codexivo también lo tiene, para practicar antes de

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexivo",
-  "version": "0.2.3",
+  "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",

package/src/catalog.ts

@@ -227,6 +227,7 @@ const library: ProcedureEntry[] = [
 const CATEGORIES: ProcedureCategory[] = [
   'entrada y salida',
   'tipos',
+  'verificación',
   'matemáticas',
   'texto',
   'listas',

package/src/error-codes.ts

@@ -186,6 +186,11 @@ export const ERROR_CODES: Readonly<Record<string, { kind: ErrorKind; explanation
   },
 
   // ejecución
+  AFIRMACIÓN_FALLIDA: {
+    kind: 'ejecución',
+    explanation:
+      'Una llamada a `afirmar(condición, mensaje)` encontró que su condición era falsa. Afirmar es escribir lo que esperas que sea cierto en ese punto del programa; si no lo es, el programa se detiene ahí, antes de que el error llegue más lejos. Revisa los valores de las variables justo antes de esa línea.',
+  },
   CANTIDAD_DE_ARGUMENTOS: {
     kind: 'ejecución',
     explanation:

package/src/runtime/builtins.ts

@@ -358,6 +358,50 @@ const library: NativeValue[] = [
     },
   ),
 
+  // verificación
+  define(
+    'afirmar',
+    [1, 2],
+    {
+      level: 'principiante',
+      category: 'verificación',
+      params: [
+        { name: 'condición', type: 'lógico' },
+        { name: 'mensaje', type: 'texto', optional: true },
+      ],
+      returns: 'nulo',
+      description:
+        'Detiene el programa con un error si la condición es falsa. Sirve para escribir lo que esperas que sea cierto y comprobarlo.',
+      examples: [
+        { code: 'variable total = 2 + 2\nafirmar(total es_igual_a 4, "la suma está mal")\ntotal', result: '4' },
+      ],
+    },
+    (args, context) => {
+      const condition = args[0]!;
+      if (typeof condition !== 'boolean') {
+        throw context.fail(
+          'TIPO_DE_ARGUMENTO',
+          `\`afirmar\` espera una condición \`verdadero\` o \`falso\`, pero recibió ${describeType(typeOf(condition))} (${repr(condition)}).`,
+          '¿Quisiste comparar? Por ejemplo: `afirmar(x es_mayor_que 0)`.',
+        );
+      }
+      const message = args[1];
+      if (message !== undefined && typeof message !== 'string') {
+        throw context.fail(
+          'TIPO_DE_ARGUMENTO',
+          `El mensaje de \`afirmar\` tiene que ser un texto, pero es ${describeType(typeOf(message))}.`,
+          'Escribe el mensaje entre comillas: `afirmar(x es_mayor_que 0, "x tenía que ser positivo")`.',
+        );
+      }
+      if (condition) return null;
+      throw context.fail(
+        'AFIRMACIÓN_FALLIDA',
+        message ? `La afirmación no se cumplió: ${message}` : 'La afirmación no se cumplió.',
+        'Lo que afirmaste que era cierto no lo es en este punto. Revisa los valores de las variables justo antes de esta línea.',
+      );
+    },
+  ),
+
   // matemáticas
   define(
     'absoluto',

package/src/runtime/values.ts

@@ -68,6 +68,7 @@ export type ProcedureLevel = 'principiante' | 'intermedio' | 'avanzado';
 export type ProcedureCategory =
   | 'entrada y salida'
   | 'tipos'
+  | 'verificación'
   | 'matemáticas'
   | 'texto'
   | 'listas'