codexivo 0.0.0-stage → 0.2.3

package/src/syntax/ast.ts

@@ -0,0 +1,344 @@
+import type { Span } from './token';
+
+/**
+ * El AST está hecho de objetos planos: se puede serializar, enviar a un Web Worker y dibujar sin
+ * perder información. Cada nodo tiene un `id` único dentro de su programa y su rango en el código.
+ */
+interface BaseNode {
+  id: number;
+  span: Span;
+}
+
+/** `%` y `mod` son el mismo operador; en el AST siempre aparece como `mod`. */
+export type BinaryOperator = '+' | '-' | '*' | '/' | 'div' | 'mod' | '^' | '==' | '!=' | '<' | '>' | '<=' | '>=';
+export type LogicalOperator = 'y' | 'o';
+export type UnaryOperator = '-' | 'no';
+export type AssignmentOperator = '=' | '+=' | '-=' | '*=' | '/=' | '%=';
+export type IncrementOperator = '++' | '--';
+
+// ── expresiones ──────────────────────────────────────────────────────────────
+
+export interface NumberLiteral extends BaseNode {
+  kind: 'NumberLiteral';
+  value: number;
+}
+
+export interface StringLiteral extends BaseNode {
+  kind: 'StringLiteral';
+  value: string;
+}
+
+export interface BooleanLiteral extends BaseNode {
+  kind: 'BooleanLiteral';
+  value: boolean;
+}
+
+export interface NullLiteral extends BaseNode {
+  kind: 'NullLiteral';
+}
+
+export interface ListLiteral extends BaseNode {
+  kind: 'ListLiteral';
+  elements: Expression[];
+}
+
+export interface Identifier extends BaseNode {
+  kind: 'Identifier';
+  name: string;
+}
+
+export interface Unary extends BaseNode {
+  kind: 'Unary';
+  operator: UnaryOperator;
+  operand: Expression;
+}
+
+export interface Binary extends BaseNode {
+  kind: 'Binary';
+  operator: BinaryOperator;
+  left: Expression;
+  right: Expression;
+}
+
+/** `y` / `o`: se evalúan en cortocircuito, por eso no son un `Binary`. */
+export interface Logical extends BaseNode {
+  kind: 'Logical';
+  operator: LogicalOperator;
+  left: Expression;
+  right: Expression;
+}
+
+export interface Call extends BaseNode {
+  kind: 'Call';
+  callee: Expression;
+  args: Expression[];
+}
+
+export interface Index extends BaseNode {
+  kind: 'Index';
+  object: Expression;
+  index: Expression;
+  /** `true` si se escribió `d.campo`; entonces `index` es el texto `"campo"`. */
+  dot?: boolean;
+}
+
+export interface DictEntry {
+  /** Rango de `clave: valor`. */
+  span: Span;
+  key: Expression;
+  value: Expression;
+}
+
+export interface DictLiteral extends BaseNode {
+  kind: 'DictLiteral';
+  entries: DictEntry[];
+}
+
+export interface FunctionLiteral extends BaseNode {
+  kind: 'FunctionLiteral';
+  /** Nombre con el que se declaró, si se conoce (`variable doble = procedimiento…` → `doble`). */
+  name?: string;
+  params: Identifier[];
+  body: Block;
+}
+
+export type Expression =
+  | NumberLiteral
+  | StringLiteral
+  | BooleanLiteral
+  | NullLiteral
+  | ListLiteral
+  | DictLiteral
+  | Identifier
+  | Unary
+  | Binary
+  | Logical
+  | Call
+  | Index
+  | FunctionLiteral;
+
+// ── sentencias ───────────────────────────────────────────────────────────────
+
+export interface VariableDeclaration extends BaseNode {
+  kind: 'VariableDeclaration';
+  /** `true` si se declaró con `constante`: no se puede reasignar. */
+  constant: boolean;
+  name: Identifier;
+  value: Expression;
+}
+
+/** Lo que puede ir a la izquierda de `=`: una variable o un elemento (`lista[i]`). */
+export type AssignmentTarget = Identifier | Index;
+
+export interface Assignment extends BaseNode {
+  kind: 'Assignment';
+  target: AssignmentTarget;
+  operator: AssignmentOperator;
+  value: Expression;
+}
+
+/** `i++` / `i--`: son sentencias, no expresiones. */
+export interface Increment extends BaseNode {
+  kind: 'Increment';
+  target: AssignmentTarget;
+  operator: IncrementOperator;
+}
+
+/** `procedimiento nombre(…) { … }`: se puede usar desde el inicio de su bloque. */
+export interface FunctionDeclaration extends BaseNode {
+  kind: 'FunctionDeclaration';
+  name: Identifier;
+  function: FunctionLiteral;
+}
+
+export interface ExpressionStatement extends BaseNode {
+  kind: 'ExpressionStatement';
+  expression: Expression;
+}
+
+export interface Return extends BaseNode {
+  kind: 'Return';
+  value?: Expression;
+}
+
+export interface Block extends BaseNode {
+  kind: 'Block';
+  statements: Statement[];
+}
+
+export interface IfBranch {
+  /** Rango de la rama completa: desde `si` / `pero_si` hasta su `}`. */
+  span: Span;
+  condition: Expression;
+  body: Block;
+}
+
+/** `si … pero_si … si_no`: las ramas se guardan en orden, no anidadas. */
+export interface If extends BaseNode {
+  kind: 'If';
+  branches: IfBranch[];
+  alternative?: Block;
+}
+
+export interface While extends BaseNode {
+  kind: 'While';
+  condition: Expression;
+  body: Block;
+}
+
+/** `hacer { … } hasta_que (condición)`: repite el cuerpo hasta que la condición sea verdadera. */
+export interface DoUntil extends BaseNode {
+  kind: 'DoUntil';
+  body: Block;
+  condition: Expression;
+}
+
+export interface For extends BaseNode {
+  kind: 'For';
+  init?: VariableDeclaration | Assignment | Increment | ExpressionStatement;
+  condition?: Expression;
+  update?: Assignment | Increment | ExpressionStatement;
+  body: Block;
+}
+
+/**
+ * `para i desde a hasta b con_paso p { … }`: cuenta de `a` a `b`, incluidos los dos. Los límites y el paso se
+ * evalúan una vez, al empezar; `i` es nueva en cada vuelta y no se puede cambiar dentro del cuerpo.
+ */
+export interface ForRange extends BaseNode {
+  kind: 'ForRange';
+  variable: Identifier;
+  from: Expression;
+  to: Expression;
+  step?: Expression;
+  body: Block;
+}
+
+/** `repetir n veces { … }`: el contador es interno, no una variable visible. */
+export interface Repeat extends BaseNode {
+  kind: 'Repeat';
+  count: Expression;
+  body: Block;
+}
+
+/** `para_cada x en lista { … }`: recorre una lista o un texto. */
+export interface ForEach extends BaseNode {
+  kind: 'ForEach';
+  variable: Identifier;
+  /** Segunda variable de `para_cada clave, valor en diccionario`. */
+  value?: Identifier;
+  iterable: Expression;
+  body: Block;
+}
+
+/**
+ * `dominio nombre { … }`: un espacio de nombres. Agrupa declaraciones (variables, constantes, procedimientos y
+ * otros dominios) que se usan desde fuera con `nombre.miembro`. No es un módulo: no hay `importar`.
+ */
+export interface Domain extends BaseNode {
+  kind: 'Domain';
+  name: Identifier;
+  body: Block;
+}
+
+export interface Break extends BaseNode {
+  kind: 'Break';
+}
+
+export interface Continue extends BaseNode {
+  kind: 'Continue';
+}
+
+export type Statement =
+  | VariableDeclaration
+  | FunctionDeclaration
+  | Assignment
+  | Increment
+  | ExpressionStatement
+  | Return
+  | Block
+  | If
+  | While
+  | DoUntil
+  | For
+  | ForRange
+  | ForEach
+  | Repeat
+  | Break
+  | Continue
+  | Domain;
+
+export interface Program extends BaseNode {
+  kind: 'Program';
+  statements: Statement[];
+}
+
+export type Node = Program | Statement | Expression;
+
+/** Hijos directos de un nodo, en el orden en que aparecen en el código. */
+export const childrenOf = (node: Node): Node[] => {
+  switch (node.kind) {
+    case 'Program':
+    case 'Block':
+      return node.statements;
+    case 'ListLiteral':
+      return node.elements;
+    case 'DictLiteral':
+      return node.entries.flatMap(entry => [entry.key, entry.value]);
+    case 'Unary':
+      return [node.operand];
+    case 'Binary':
+    case 'Logical':
+      return [node.left, node.right];
+    case 'Call':
+      return [node.callee, ...node.args];
+    case 'Index':
+      return [node.object, node.index];
+    case 'FunctionLiteral':
+      return [...node.params, node.body];
+    case 'VariableDeclaration':
+      return [node.name, node.value];
+    case 'Assignment':
+      return [node.target, node.value];
+    case 'Increment':
+      return [node.target];
+    case 'FunctionDeclaration':
+      return [node.name, node.function];
+    case 'ForEach':
+      return [node.variable, ...(node.value ? [node.value] : []), node.iterable, node.body];
+    case 'ExpressionStatement':
+      return [node.expression];
+    case 'Return':
+      return node.value ? [node.value] : [];
+    case 'If':
+      return [
+        ...node.branches.flatMap(branch => [branch.condition, branch.body]),
+        ...(node.alternative ? [node.alternative] : []),
+      ];
+    case 'While':
+      return [node.condition, node.body];
+    case 'DoUntil':
+      return [node.body, node.condition];
+    case 'Domain':
+      return [node.name, node.body];
+    case 'ForRange':
+      return [node.variable, node.from, node.to, ...(node.step ? [node.step] : []), node.body];
+    case 'Repeat':
+      return [node.count, node.body];
+    case 'For':
+      return [
+        ...(node.init ? [node.init] : []),
+        ...(node.condition ? [node.condition] : []),
+        ...(node.update ? [node.update] : []),
+        node.body,
+      ];
+    default:
+      return [];
+  }
+};
+
+/** Recorre el árbol en profundidad, del padre a los hijos. */
+export const walk = (node: Node, visit: (node: Node, parent?: Node) => void, parent?: Node): void => {
+  visit(node, parent);
+  for (const child of childrenOf(node)) walk(child, visit, node);
+};

package/src/syntax/lexer.ts

@@ -0,0 +1,266 @@
+import { CodexivoError } from '../errors';
+import { KEYWORDS, TokenType } from './token';
+import type { Position, Span, Token } from './token';
+
+export interface LexResult {
+  tokens: Token[];
+  errors: CodexivoError[];
+}
+
+const LETTER = /[A-Za-z_À-ÖØ-öø-ÿ]/;
+const DIGIT = /[0-9]/;
+const WHITESPACE = /\s/;
+
+const TWO_CHAR_OPERATORS: Readonly<Record<string, TokenType>> = {
+  '==': TokenType.EQ,
+  '!=': TokenType.NEQ,
+  '<=': TokenType.LTE,
+  '>=': TokenType.GTE,
+  '+=': TokenType.PLUS_ASSIGN,
+  '-=': TokenType.MINUS_ASSIGN,
+  '*=': TokenType.STAR_ASSIGN,
+  '/=': TokenType.SLASH_ASSIGN,
+  '%=': TokenType.PERCENT_ASSIGN,
+  '++': TokenType.INCREMENT,
+  '--': TokenType.DECREMENT,
+};
+
+const ONE_CHAR_OPERATORS: Readonly<Record<string, TokenType>> = {
+  '=': TokenType.ASSIGN,
+  '+': TokenType.PLUS,
+  '-': TokenType.MINUS,
+  '*': TokenType.STAR,
+  '/': TokenType.SLASH,
+  '%': TokenType.PERCENT,
+  '^': TokenType.CARET,
+  '!': TokenType.BANG,
+  '<': TokenType.LT,
+  '>': TokenType.GT,
+  ',': TokenType.COMMA,
+  ':': TokenType.COLON,
+  '.': TokenType.DOT,
+  ';': TokenType.SEMICOLON,
+  '(': TokenType.LPAREN,
+  ')': TokenType.RPAREN,
+  '{': TokenType.LBRACE,
+  '}': TokenType.RBRACE,
+  '[': TokenType.LBRACKET,
+  ']': TokenType.RBRACKET,
+};
+
+const VALUE_ENDS = new Set([
+  TokenType.IDENT,
+  TokenType.NUMBER,
+  TokenType.STRING,
+  TokenType.RPAREN,
+  TokenType.RBRACKET,
+  TokenType.RBRACE,
+]);
+
+const ESCAPES: Readonly<Record<string, string>> = {
+  n: '\n',
+  t: '\t',
+  '\\': '\\',
+  '"': '"',
+  "'": "'",
+};
+
+const ILLEGAL_HINTS: Readonly<Record<string, string>> = {
+  '&': 'Para el «y» lógico escribe la palabra `y`.',
+  '|': 'Para el «o» lógico escribe la palabra `o`.',
+  '“': 'Parece una comilla tipográfica; usa comillas rectas `"`.',
+  '”': 'Parece una comilla tipográfica; usa comillas rectas `"`.',
+  '‘': "Parece una comilla tipográfica; usa comillas rectas `'`.",
+  '’': "Parece una comilla tipográfica; usa comillas rectas `'`.",
+};
+
+/** Convierte código fuente en tokens. Nunca lanza: los problemas se reportan en `errors`. */
+export const tokenize = (source: string): LexResult => {
+  const tokens: Token[] = [];
+  const errors: CodexivoError[] = [];
+
+  let offset = 0;
+  let line = 1;
+  let column = 1;
+
+  const position = (): Position => ({ line, column, offset });
+  const peek = (ahead = 0): string => source[offset + ahead] ?? '';
+  const advance = (): string => {
+    const character = source[offset] ?? '';
+    offset += 1;
+    if (character === '\n') {
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+    return character;
+  };
+
+  const push = (type: TokenType, start: Position, value?: number | string): Token => {
+    const token: Token = { type, lexeme: source.slice(start.offset, offset), span: { start, end: position() } };
+    if (value !== undefined) token.value = value;
+    tokens.push(token);
+    return token;
+  };
+
+  const lexicalError = (code: string, message: string, span: Span, hint?: string) => {
+    errors.push(new CodexivoError({ kind: 'léxico', code, message, hint, span }));
+  };
+
+  while (offset < source.length) {
+    const character = peek();
+
+    if (WHITESPACE.test(character)) {
+      advance();
+      continue;
+    }
+
+    const start = position();
+
+    // comentarios
+    if (character === '/' && peek(1) === '/') {
+      while (offset < source.length && peek() !== '\n') advance();
+      continue;
+    }
+    if (character === '/' && peek(1) === '*') {
+      advance();
+      advance();
+      while (offset < source.length && !(peek() === '*' && peek(1) === '/')) advance();
+      if (offset >= source.length) {
+        lexicalError(
+          'COMENTARIO_SIN_CERRAR',
+          'El comentario que empieza aquí no se cerró.',
+          {
+            start,
+            end: { line: start.line, column: start.column + 2, offset: start.offset + 2 },
+          },
+          'Cierra el comentario con `*/`.',
+        );
+      } else {
+        advance();
+        advance();
+      }
+      continue;
+    }
+
+    // números
+    // Después de un valor, `.` es acceso a un campo (`d.1` es un error claro, no `d` seguido de `.1`).
+    const last = tokens[tokens.length - 1];
+    const afterValue = last !== undefined && VALUE_ENDS.has(last.type) && last.span.end.offset === offset;
+    if (DIGIT.test(character) || (character === '.' && DIGIT.test(peek(1)) && !afterValue)) {
+      // `_` separa grupos de dígitos (`1_000_000`); se revisa que esté bien puesto al final.
+      const digits = () => {
+        while (DIGIT.test(peek()) || peek() === '_') advance();
+      };
+      digits();
+      if (peek() === '.' && DIGIT.test(peek(1))) {
+        advance();
+        digits();
+      }
+      if (LETTER.test(peek()) && peek() !== '_') {
+        while (LETTER.test(peek()) || DIGIT.test(peek())) advance();
+        const token = push(TokenType.ILLEGAL, start);
+        lexicalError(
+          'NOMBRE_EMPIEZA_CON_NÚMERO',
+          `\`${token.lexeme}\` no es un número ni un nombre válido.`,
+          token.span,
+          'Los nombres no pueden empezar con un dígito. Si es una multiplicación, escribe el operador: `2 * x`.',
+        );
+        continue;
+      }
+      const text = source.slice(start.offset, offset);
+      if (/(^|\D)_|_(\D|$)/.test(text)) {
+        const token = push(TokenType.ILLEGAL, start);
+        lexicalError(
+          'SEPARADOR_INVÁLIDO',
+          `\`${text}\` no es un número válido.`,
+          token.span,
+          'El `_` solo puede ir entre dos dígitos para separar grupos, como en `1_000_000`.',
+        );
+        continue;
+      }
+      push(TokenType.NUMBER, start, Number(text.replaceAll('_', '')));
+      continue;
+    }
+
+    // nombres y palabras reservadas
+    if (LETTER.test(character)) {
+      while (LETTER.test(peek()) || DIGIT.test(peek())) advance();
+      const word = source.slice(start.offset, offset);
+      push(KEYWORDS[word] ?? TokenType.IDENT, start);
+      continue;
+    }
+
+    // textos
+    if (character === '"' || character === "'") {
+      const quote = advance();
+      let value = '';
+      let closed = false;
+      while (offset < source.length && peek() !== '\n') {
+        const current = advance();
+        if (current === quote) {
+          closed = true;
+          break;
+        }
+        if (current === '\\') {
+          const escapeStart = { line, column: column - 1, offset: offset - 1 };
+          const escaped = advance();
+          const replacement = ESCAPES[escaped];
+          if (replacement === undefined) {
+            lexicalError(
+              'ESCAPE_DESCONOCIDO',
+              `\`\\${escaped}\` no es una secuencia de escape válida.`,
+              { start: escapeStart, end: position() },
+              'Las secuencias válidas son `\\n`, `\\t`, `\\\\`, `\\"` y `\\\'`.',
+            );
+            value += escaped;
+          } else {
+            value += replacement;
+          }
+          continue;
+        }
+        value += current;
+      }
+      const token = push(TokenType.STRING, start, value);
+      if (!closed) {
+        lexicalError(
+          'TEXTO_SIN_CERRAR',
+          'El texto que empieza aquí no se cerró.',
+          token.span,
+          `Agrega la comilla \`${quote}\` al final. Un texto no puede ocupar varias líneas; usa \`\\n\` para un salto de línea.`,
+        );
+      }
+      continue;
+    }
+
+    // operadores y delimitadores
+    const pair = character + peek(1);
+    const twoChar = TWO_CHAR_OPERATORS[pair];
+    if (twoChar) {
+      advance();
+      advance();
+      push(twoChar, start);
+      continue;
+    }
+    const oneChar = ONE_CHAR_OPERATORS[character];
+    if (oneChar) {
+      advance();
+      push(oneChar, start);
+      continue;
+    }
+
+    advance();
+    const token = push(TokenType.ILLEGAL, start);
+    lexicalError(
+      'CARÁCTER_DESCONOCIDO',
+      `Codexivo no reconoce el carácter \`${character}\`.`,
+      token.span,
+      ILLEGAL_HINTS[character],
+    );
+  }
+
+  const end = position();
+  tokens.push({ type: TokenType.EOF, lexeme: '', span: { start: end, end } });
+  return { tokens, errors };
+};