@ascent-lang/dev 0.1.0 → 0.2.0

package/src/errors/syntactic.yml

@@ -1,66 +1,145 @@
-# S — syntactic: the tokens don't form a valid expression
+# S — syntactic: each word is fine on its own, but they don't fit together
 
-- code: 'S0001'
-  name: 'unclosed-paren'
-  category: 'syntactic'
+- code: S0001
+  name: unclosed-paren
+  category: syntactic
   summary: "An opening '(' has no matching ')'."
+  message: "I expected a ')' here."
+  explanation: >-
+    Every '(' has to be closed with a matching ')'. One was opened earlier —
+    around a group like '(a + b)', a call's inputs, or an 'if' or 'while'
+    condition — and this is where its ')' should be.
+  related:
+    - key: opener
+      label: "this '(' was opened here"
 
-- code: 'S0002'
-  name: 'expected-expression'
-  category: 'syntactic'
-  summary: 'An expression was required here but the input contained none.'
+- code: S0002
+  name: expected-expression
+  category: syntactic
+  summary: A value was expected here, but there wasn't one.
+  message: "I expected a value here."
+  explanation: >-
+    This spot needs a value — a number, a String, a name, or something built
+    from them like 'a + b'. Places that need one include just after '=', just
+    after an operator like '+', and inside '( )'.
 
-- code: 'S0003'
-  name: 'expected-slot-name'
-  category: 'syntactic'
-  summary: "A slot name (lowercase identifier) was expected after 'fix'."
+- code: S0003
+  name: expected-slot-name
+  category: syntactic
+  summary: "A name was expected after 'fix' or 'mut', or as a program input."
+  message: "I expected a name here."
+  explanation: >-
+    A name is needed here — after 'fix' or 'mut' to create one
+    ('fix count = 0'), or as the name of a program input ('args (age: Int)'). A
+    name starts with a lowercase letter.
 
-- code: 'S0004'
-  name: 'expected-equals'
-  category: 'syntactic'
-  summary: "An '=' was expected after the slot name in a 'fix' declaration."
+- code: S0004
+  name: expected-equals
+  category: syntactic
+  summary: "An '=' was expected after the name in a 'fix' or 'mut' declaration."
+  message: "I expected an '=' here."
+  explanation: >-
+    'fix' and 'mut' give a name its starting value, so the name is followed by
+    '=' and the value, like 'fix count = 0'. (A type can go in between, as in
+    'fix count: Int = 0'.)
 
-- code: 'S0005'
-  name: 'unclosed-brace'
-  category: 'syntactic'
+- code: S0005
+  name: unclosed-brace
+  category: syntactic
   summary: "An opening '{' has no matching '}'."
+  message: "I expected a '}' here."
+  explanation: >-
+    A block groups statements between '{' and '}'. One was opened earlier and
+    this is where its closing '}' should be.
+  related:
+    - key: opener
+      label: "this '{' was opened here"
 
-- code: 'S0006'
-  name: 'expected-test-paren'
-  category: 'syntactic'
-  summary: "An '(' was expected here to start the condition."
+- code: S0006
+  name: expected-test-paren
+  category: syntactic
+  summary: "A '(' was expected to open a condition or an 'args' list."
+  message: "I expected a '(' here."
+  explanation: >-
+    An 'if' or 'while' condition — and the inputs listed after 'args' — go
+    inside '( )', like 'if (age >= 18) { … }'. This is where that opening '('
+    should be.
 
-- code: 'S0007'
-  name: 'expected-block'
-  category: 'syntactic'
+- code: S0007
+  name: expected-block
+  category: syntactic
   summary: "A block ('{ … }') was expected here."
+  message: "I expected a '{' here."
+  explanation: >-
+    The body of an 'if', 'else', or 'while' is always a block between '{' and
+    '}', even when it holds a single line, as in 'if (ok) { … }'.
 
-- code: 'S0008'
-  name: 'chained-comparison'
-  category: 'syntactic'
-  summary: "Comparisons don't chain — 'a < b < c' isn't valid. Group with parentheses instead."
+- code: S0008
+  name: chained-comparison
+  category: syntactic
+  summary: "Comparisons can't be chained — 'a < b < c' isn't allowed."
+  message: "I can't chain two comparisons like this."
+  explanation: >-
+    A comparison such as '<' or '==' looks at two values and gives back True or
+    False. Chaining a third one, as in 'a < b < c', would then compare that
+    True or False against another value, which has no clear meaning — so
+    compare two values at a time.
 
-- code: 'S0009'
-  name: 'expected-colon'
-  category: 'syntactic'
-  summary: "A ':' was expected between the argument name and its type."
+- code: S0009
+  name: expected-colon
+  category: syntactic
+  summary: "A ':' was expected between a program input's name and its type."
+  message: "I expected a ':' here."
+  explanation: >-
+    Each program input is written as a name, then ':', then its type, like
+    'args (age: Int)'. This is where the ':' should be.
 
-- code: 'S0010'
-  name: 'expected-type'
-  category: 'syntactic'
-  summary: "A type name was expected here. Valid types are Int, Float, Bool, String, and List<T>."
+- code: S0010
+  name: expected-type
+  category: syntactic
+  summary: A type name was expected here.
+  message: "I expected a type name here."
+  explanation: >-
+    A type name says what kind of value this is. The built-in types are Int,
+    Float, Bool, and String, plus 'List<…>' for a list, as in 'List<Int>'.
 
-- code: 'S0011'
-  name: 'expected-semicolon'
-  category: 'syntactic'
-  summary: "A ';' was expected here."
+- code: S0011
+  name: expected-semicolon
+  category: syntactic
+  summary: "A ';' was expected to end the statement."
+  message: "I expected a ';' here."
+  explanation: >-
+    Every statement in Ascent ends with a ';'. It looks like the statement
+    before this point was never finished with one.
 
-- code: 'S0012'
-  name: 'expected-method-name'
-  category: 'syntactic'
-  summary: "A method name (lowercase identifier) was expected after '.'."
+- code: S0012
+  name: expected-method-name
+  category: syntactic
+  summary: "A method name was expected after '.'."
+  message: "I expected a method name here."
+  explanation: >-
+    A '.' calls a method on a value, so it's followed by the method's name and
+    '( )', like 'items.length()'. A method name starts with a lowercase letter.
 
-- code: 'S0013'
-  name: 'unclosed-bracket'
-  category: 'syntactic'
+- code: S0013
+  name: unclosed-bracket
+  category: syntactic
   summary: "An opening '[' has no matching ']'."
+  message: "I expected a ']' here."
+  explanation: >-
+    Square brackets '[ ]' wrap a list like '[1, 2, 3]' or pick an item out of
+    one like 'items[0]'. One '[' was opened earlier and this is where its ']'
+    should be.
+  related:
+    - key: opener
+      label: "this '[' was opened here"
+
+- code: S0014
+  name: expected-call-paren
+  category: syntactic
+  summary: "A method call needs '( )' after the method name."
+  message: "I expected a '(' here."
+  explanation: >-
+    A '.' calls a method, and a call always has '( )' after the name — even
+    when the method takes no inputs, as in 'items.length()'. This is where that
+    opening '(' should be.

package/src/errors/typechecker.yml

@@ -1,61 +1,147 @@
-# T — type: a type rule is broken
-
-- code: 'T0001'
-  name: 'annotation-mismatch'
-  category: 'type'
-  summary: "The declared type annotation doesn't match the inferred type of the initialiser."
-
-- code: 'T0002'
-  name: 'incompatible-list-elements'
-  category: 'type'
-  summary: "List elements have incompatible types — a list must be homogeneous (all the same type, with Int widening to Float)."
-
-- code: 'T0003'
-  name: 'empty-list-needs-annotation'
-  category: 'type'
-  summary: "An empty list '[]' has no element type. Annotate the variable: 'fix xs: List<Int> = []'."
-
-- code: 'T0004'
-  name: 'condition-not-bool'
-  category: 'type'
-  summary: "The condition in 'if' or 'while' must be of type Bool."
-
-- code: 'T0005'
-  name: 'if-branch-mismatch'
-  category: 'type'
-  summary: "The 'then' and 'else' branches of 'if' have incompatible types."
-
-- code: 'T0006'
-  name: 'no-such-method'
-  category: 'type'
-  summary: "The type has no method with this name."
-
-- code: 'T0007'
-  name: 'wrong-arg-count'
-  category: 'type'
-  summary: "Wrong number of arguments for this method or function call."
-
-- code: 'T0008'
-  name: 'wrong-arg-type'
-  category: 'type'
-  summary: "An argument has the wrong type for this method or function call."
-
-- code: 'T0009'
-  name: 'operator-type-error'
-  category: 'type'
-  summary: "An operator was applied to operands of incompatible types."
-
-- code: 'T0010'
-  name: 'index-requires-list'
-  category: 'type'
-  summary: "The '[ ]' index operator requires a List, but the receiver has a different type."
-
-- code: 'T0011'
-  name: 'index-not-int'
-  category: 'type'
-  summary: "List indices must be of type Int."
-
-- code: 'T0012'
-  name: 'no-methods'
-  category: 'type'
-  summary: "This type has no methods."
+# T — type: the code fits together, but the types don't line up
+#
+# Same shape as the other error files. Type errors need words the source can't
+# supply — the actual type names ('Int', 'String'), an argument count — so the
+# checker sends them along as data and the messages drop them in as {expected},
+# {actual}, {type}, {op}, and so on. Related spans point at the other places
+# that matter: the two branches of an 'if', the item that breaks a list, the
+# annotation a value was measured against. See lexical.yml for the wording rules.
+
+- code: T0001
+  name: annotation-mismatch
+  category: type
+  summary: A value's type doesn't match the type expected here (a written annotation, or the name's existing type).
+  message: "This value has type {actual}, but {expected} was expected here."
+  explanation: >-
+    A value's type has to fit the type asked for in this spot. Here the value is
+    {actual} and {expected} was expected, and those don't match. (An Int can go
+    where a Float is expected, but not the other way around.)
+  related:
+    - key: annotation
+      label: "the type was set to {expected} here"
+    - key: declaration
+      label: "this was created holding {expected}"
+
+- code: T0002
+  name: incompatible-list-elements
+  category: type
+  summary: A list mixes items of types that have no common type.
+  message: "The items in this list don't all have the same type."
+  explanation: >-
+    Every item in a list shares one type. Some items here are {first}, but this
+    one is {other}, and those don't fit together. (A mix of Int and Float is
+    fine — the Ints become Floats — but unrelated types like Int and String
+    can't share a list.)
+  related:
+    - key: element
+      label: "this item is {other}"
+
+- code: T0003
+  name: empty-list-needs-annotation
+  category: type
+  summary: An empty list has no items to show its type, and none was written down.
+  message: "This empty list needs a type."
+  explanation: >-
+    An empty list '[]' has no items to show what it holds, so its type has to be
+    written down — for example 'fix xs: List<Int> = []'.
+
+- code: T0004
+  name: condition-not-bool
+  category: type
+  summary: "The condition of an 'if' or 'while' isn't a True/False value."
+  message: "This condition has type {actual}, but it has to be True or False."
+  explanation: >-
+    An 'if' or 'while' chooses what to do from a True/False value, so its
+    condition has to be one — a comparison like 'x > 0', or another Bool. This
+    one has type {actual}.
+
+- code: T0005
+  name: if-branch-mismatch
+  category: type
+  summary: "The two branches of an 'if' produce different types."
+  message: "The two branches of this 'if' have different types."
+  explanation: >-
+    When an 'if' is used as a value, both branches have to produce the same
+    type, because the whole 'if' becomes one value. Here one branch gives
+    {then} and the other gives {else}.
+  related:
+    - key: then
+      label: "this branch gives {then}"
+    - key: else
+      label: "this branch gives {else}"
+
+- code: T0006
+  name: no-such-method
+  category: type
+  summary: A method with this name doesn't exist on the value's type.
+  message: "{type} has no method called '{method}'."
+  explanation: >-
+    The methods you can call depend on the value's type. For example, an Int has
+    'toStr()', 'toFloat()', and 'abs()'; a list has 'length()', 'append(…)',
+    'reverse()', and more. Check the spelling of '{method}'.
+
+- code: T0007
+  name: wrong-arg-count
+  category: type
+  summary: A method or function call was given the wrong number of inputs.
+  message: "This call has the wrong number of inputs."
+  explanation: >-
+    It needs {expected}, but was given {got}. Each input goes inside the '( )',
+    separated by commas.
+
+- code: T0008
+  name: wrong-arg-type
+  category: type
+  summary: An input to a method or function has a type that isn't accepted here.
+  message: "This input has type {actual}, but {expected} was expected."
+  explanation: >-
+    Each method or function accepts inputs of certain types. Here {expected} was
+    expected, but the input given is {actual}.
+
+- code: T0009
+  name: operator-type-error
+  category: type
+  summary: An operator was used on types it doesn't accept.
+  message: "I can't use '{op}' on {operands}."
+  explanation: >-
+    Operators only work on certain types: '+', '-', '*', and '/' need numbers
+    (Int or Float); 'div' and 'mod' need whole numbers (Int); 'and', 'or', and 'not' need True/False values (Bool); and a comparison needs two
+    values of the same kind. '{op}' doesn't work on {operands}.
+
+- code: T0010
+  name: index-requires-list
+  category: type
+  summary: "The '[ ]' index was used on something that isn't a list."
+  message: "I can't use '[ ]' here — this has type {actual}, not a list."
+  explanation: >-
+    Reading an item with '[ ]', like 'items[0]', works only on a list. This
+    value has type {actual}, which isn't a list.
+
+- code: T0011
+  name: index-not-int
+  category: type
+  summary: A list index isn't an Int.
+  message: "A list index has to be an Int, but this has type {actual}."
+  explanation: >-
+    Inside 'items[…]', the value in the brackets picks an item by its position,
+    counting from 0, so it has to be a whole number (Int). This one has type
+    {actual}.
+
+- code: T0012
+  name: no-methods
+  category: type
+  summary: The value's type has no methods at all.
+  message: "Values of type {type} don't have any methods."
+  explanation: >-
+    Only some types have methods you can call with '.': Int, Float, and List. A
+    {type} has none, so 'value.something()' can't be used on it.
+
+- code: T0013
+  name: unknown-function
+  category: type
+  summary: A call names a function that doesn't exist.
+  message: "There's no function called '{name}'."
+  explanation: >-
+    Ascent has just one built-in function right now — 'floor(x)', which rounds a
+    Float down to a whole number. Everything else is a method, called on a value
+    with '.', like 'x.toStr()'.

package/src/errors/types.ts

@@ -4,10 +4,65 @@
 
 export type Category = 'lexical' | 'syntactic' | 'name' | 'type' | 'runtime';
 
+// A concrete, machine-applicable correction. Authored ONLY when the fix is
+// certain and unambiguous (see the wording rules in the .yml files); an
+// uncertain guess is left to the reader / the LLM engine, not baked in here.
+export interface Fix {
+  title: string;        // human label for the action, e.g. "Write '0.5'"
+  replacement: string;  // text to put in place of the offending span
+}
+
+// A generic illustration of the rule — NOT "your code, fixed". `valid` shows a
+// well-formed form, `invalid` a broken one, so the pair teaches the rule
+// without guessing what the author actually meant.
+export interface Example {
+  valid: string;
+  invalid: string;
+}
+
+// A label for a supporting span. `key` pairs it with the RelatedMarker the
+// checker emits (by role); `label` is the prose shown beside that span and may
+// contain {found}. If the checker doesn't supply a span for this key (e.g. the
+// declaration has no source location), the label is simply dropped.
+export interface RelatedLabel {
+  key: string;
+  label: string;
+}
+
+// A condition on the offending source text (`found`). The first variant whose
+// `when` matches overrides the base fields it specifies. Kept deliberately tiny
+// — these two forms cover every value-keyed case the lexer produces.
+export interface When {
+  equals?: string;
+  startsWith?: string;
+}
+
+// A tailored override for a specific found text (e.g. a stray '!'). It overrides
+// only the fields it sets; anything unset is inherited from the base entry.
+export interface Variant {
+  when: When;
+  message?: string;
+  explanation?: string;
+  fix?: Fix;
+  example?: Example;
+}
+
 export interface ErrorEntry {
   code: string;
   name: string;
   category: Category;
+  // One neutral line for the error catalogue / docs index.
   summary: string;
+  // The in-context headline shown to the reader. May contain {found}. When
+  // absent, the elaborator falls back to `summary`.
+  message?: string;
+  // The micro-lesson: FACTS about the language rule only, in beginner words.
+  // May contain {found}. Doubles as grounding for the LLM engine.
+  explanation?: string;
+  fix?: Fix;
+  example?: Example;
+  // Labels for supporting spans, keyed to the RelatedMarkers the checker emits.
+  related?: RelatedLabel[];
+  variants?: Variant[];
   retired?: boolean;
 }

package/src/index.ts

@@ -8,6 +8,8 @@ import { typecheck } from './parser/typechecker.js';
 import { formatValue } from './parser/printer.js';
 import { formatTypedStmt } from './parser/typed-printer.js';
 import { executeStmt, executeProgram, Environment, RuntimeValue } from './interpreter.js';
+import { elaborate } from './errors/elaborate.js';
+import { renderTerminal } from './errors/render.js';
 import type { ArgDef } from './parser/ast.js';
 
 // \x01 and \x02 bracket invisible bytes so readline counts the visible
@@ -97,10 +99,14 @@ const runFile = async (filePath: string): Promise<void> => {
   const lexResult = new Lexer(src).tokenize();
   const parseResult = new Parser(lexResult.tokens).parse();
 
-  const errors = [...lexResult.errorMarkers, ...parseResult.errorMarkers];
+  // Lexer errors mask downstream parser noise: if the characters didn't form
+  // valid tokens, the parser's complaints are just echoes of that.
+  const errors = lexResult.errorMarkers.length > 0
+    ? lexResult.errorMarkers
+    : parseResult.errorMarkers;
   if (errors.length > 0) {
     for (const marker of errors) {
-      process.stderr.write(chalk.red(`[${marker.code}]`) + '\n');
+      process.stderr.write(renderTerminal(elaborate(marker, src), src, filePath) + '\n\n');
     }
     process.exit(1);
   }
@@ -110,7 +116,7 @@ const runFile = async (filePath: string): Promise<void> => {
   const typeResult = typecheck(parseResult.program);
   if (typeResult.errorMarkers.length > 0) {
     for (const marker of typeResult.errorMarkers) {
-      process.stderr.write(chalk.red(`[${marker.code}]`) + '\n');
+      process.stderr.write(renderTerminal(elaborate(marker, src), src, filePath) + '\n\n');
     }
     process.exit(1);
   }
@@ -161,13 +167,13 @@ const runRepl = async (): Promise<void> => {
       // recovery can skip a malformed statement and still finish the
       // parse, so errorMarkers — not program nullness — is what decides
       // whether it's safe to typecheck/run.
-      if (parseResult.errorMarkers.length > 0) {
-        // Only show parser errors when the lexer succeeded — if the lexer
-        // already flagged something, the parser error is a downstream echo.
-        if (lexResult.errorMarkers.length === 0) {
-          for (const marker of parseResult.errorMarkers) {
-            process.stdout.write(chalk.red(`[${marker.code}]`) + '\n');
-          }
+      if (lexResult.errorMarkers.length > 0) {
+        for (const marker of lexResult.errorMarkers) {
+          process.stdout.write(renderTerminal(elaborate(marker, line), line, null) + '\n');
+        }
+      } else if (parseResult.errorMarkers.length > 0) {
+        for (const marker of parseResult.errorMarkers) {
+          process.stdout.write(renderTerminal(elaborate(marker, line), line, null) + '\n');
         }
       } else if (parseResult.program !== null) {
         const typeResult = typecheck(parseResult.program);
@@ -175,7 +181,7 @@ const runRepl = async (): Promise<void> => {
 
         if (typeErrors.length > 0) {
           for (const marker of typeErrors) {
-            process.stdout.write(chalk.red(`[${marker.code}]`) + '\n');
+            process.stdout.write(renderTerminal(elaborate(marker, line), line, null) + '\n');
           }
         } else {
           // Print the untyped parse tree; execute the typed AST.

package/src/interpreter.ts

@@ -1,6 +1,6 @@
 import type { BinaryOp } from './parser/ast.js';
 import type { TypedExpr, TypedBlock, TypedStatement, TypedProgram } from './parser/typed-ast.js';
-import type { AscentType } from './types/types.js';
+import { INT_TYPE, subtype, type AscentType } from './types/types.js';
 
 export type RuntimeValue = (
   | { type: 'Int'; value: bigint }
@@ -54,11 +54,11 @@ export class Environment {
   }
 }
 
-// Coerce a runtime value to match a target type when the target is Float
-// and the value is Int — the only implicit widening the language allows.
+// Coerce a runtime value to match a target type, per the witness `subtype`
+// produces — currently only Int <: Float, so only an Int value ever moves.
 // All other type conversions are explicit (methods like toFloat/toInt).
 const coerce = (v: RuntimeValue, targetType: AscentType): RuntimeValue => {
-  if (targetType.kind === 'Float' && v.type === 'Int') {
+  if (v.type === 'Int' && subtype(INT_TYPE, targetType) === 'intToFloat') {
     return { type: 'Float', value: Number(v.value) };
   }
   return v;
@@ -77,7 +77,8 @@ export const evaluateExpr = (expr: TypedExpr, env: Environment): RuntimeValue =>
       }
     }
     case 'slot': {
-      // N0001 / N0002 are caught at type-check time; this is an internal guard.
+      // Name-binding errors (N0001–N0003) are caught at type-check time; this
+      // is an internal guard.
       const value = env.get(expr.name);
       if (value === undefined) throw new Error(`internal: unbound slot '${expr.name}'`);
       return value;
@@ -119,12 +120,29 @@ export const evaluateExpr = (expr: TypedExpr, env: Environment): RuntimeValue =>
     }
     case 'unary': {
       const operand = evaluateExpr(expr.operand, env);
+      if (expr.op === 'not') {
+        if (operand.type !== 'Bool') throw new Error(`internal: 'not' on ${operand.type}`);
+        return { type: 'Bool', value: !operand.value };
+      }
       if (operand.type === 'Int') return { type: 'Int', value: -operand.value };
       if (operand.type === 'Float') return { type: 'Float', value: -operand.value };
       throw new Error(`internal: unary '-' on ${operand.type}`);
     }
-    case 'binary':
+    case 'binary': {
+      // 'and'/'or' short-circuit: the left operand alone can decide the
+      // result ('False and e' / 'True or e'), so 'e' is only evaluated
+      // when it's still needed — the same laziness every mainstream
+      // language gives its logical operators.
+      if (expr.op === 'and' || expr.op === 'or') {
+        const left = evaluateExpr(expr.left, env);
+        if (left.type !== 'Bool') throw new Error(`internal: '${expr.op}' on non-Bool`);
+        if (expr.op === 'and' ? !left.value : left.value) return left;
+        const right = evaluateExpr(expr.right, env);
+        if (right.type !== 'Bool') throw new Error(`internal: '${expr.op}' on non-Bool`);
+        return right;
+      }
       return evaluateBinary(expr.op, evaluateExpr(expr.left, env), evaluateExpr(expr.right, env));
+    }
     case 'block': {
       return evaluateBlock(expr, env);
     }

package/src/lexer/index.ts

@@ -114,13 +114,14 @@ export class Lexer {
       return this.readWord();
     }
 
-    // A leading-dot float like .5 looks like a number attempt, so L0002 is
-    // more helpful than L0001 ("unexpected character").
+    // A leading-dot float like .5 is a number missing its integer part, so
+    // L0004 (its own error, with a certain '0.5' fix) is more helpful than
+    // L0001 ("unexpected character") or L0002 (a number run into letters).
     if (ch === '.' && isDigit(this.c.peek(1))) {
       const start = this.c.mark();
       this.c.advance(); // '.'
       this.consumeWhile(isDigit);
-      return this.error('L0002', this.c.spanFrom(start));
+      return this.error('L0004', this.c.spanFrom(start));
     }
 
     const start = this.c.mark();

package/src/lexer/keywords.ts

@@ -3,6 +3,9 @@ import type { TokenKind } from './token.js';
 export const KEYWORDS: Record<string, TokenKind> = {
   div: 'KW_DIV',
   mod: 'KW_MOD',
+  and: 'KW_AND',
+  or: 'KW_OR',
+  not: 'KW_NOT',
   fix: 'KW_FIX',
   mut: 'KW_MUT',
   if: 'KW_IF',