@ascent-lang/dev 0.1.0 → 0.3.0

package/src/errors/render.ts

@@ -0,0 +1,59 @@
+import chalk from 'chalk';
+import type { Span } from '../lexer/token.js';
+import type { Diagnostic } from './elaborate.js';
+
+// One span rendered as its source line plus an underline, with an optional
+// trailing label. `mark` is the underline character and `colour` tints it, so
+// the primary span (red '^') and a supporting span (cyan '-') look distinct.
+function snippet(
+  sourceLines: string[],
+  span: Span,
+  mark: string,
+  colour: (s: string) => string,
+  label: string | null,
+): string[] {
+  const line = sourceLines[span.start.line - 1] ?? '';
+  // A span may run to the line end (an unterminated string), so clamp the
+  // underline to the visible text of its starting line.
+  const endColumn = span.end.line === span.start.line ? span.end.column : line.length + 1;
+  const underline = mark.repeat(Math.max(1, endColumn - span.start.column));
+  const gutter = String(span.start.line);
+  const blank = ' '.repeat(gutter.length);
+  const caret = `${' '.repeat(span.start.column - 1)}${colour(underline)}`;
+  return [
+    `${chalk.dim(`${gutter} |`)} ${line}`,
+    `${chalk.dim(`${blank} |`)} ${label !== null ? `${caret} ${colour(label)}` : caret}`,
+  ];
+}
+
+export function renderTerminal(d: Diagnostic, source: string, filePath: string | null): string {
+  const sourceLines = source.split('\n');
+  const lines: string[] = [];
+
+  lines.push(chalk.red.bold(`Error ${d.code}`) + chalk.bold(`: ${d.message}`));
+
+  const where = filePath !== null
+    ? `${filePath}:${d.span.start.line}:${d.span.start.column}`
+    : `line ${d.span.start.line}, column ${d.span.start.column}`;
+  lines.push(chalk.dim(`  → ${where}`));
+
+  lines.push(...snippet(sourceLines, d.span, '^', chalk.red, null));
+
+  // Supporting spans (e.g. "'count' was created with 'fix' here") point back at
+  // context elsewhere in the source, each with its own snippet.
+  for (const rel of d.related) {
+    lines.push(...snippet(sourceLines, rel.span, '-', chalk.cyan, rel.label));
+  }
+
+  if (d.explanation !== null) {
+    lines.push('');
+    lines.push(d.explanation);
+  }
+
+  if (d.fix !== null) {
+    lines.push('');
+    lines.push(chalk.green(`fix: ${d.fix.title}`));
+  }
+
+  return lines.join('\n');
+}

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

@@ -3,11 +3,13 @@ import { createInterface } from 'node:readline/promises';
 import { readFile } from 'node:fs/promises';
 import chalk from 'chalk';
 import { Lexer } from './lexer/index.js';
-import { Parser } from './parser/index.js';
+import { parse, parseTokens } from './parser/index.js';
 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
@@ -94,34 +96,22 @@ const runFile = async (filePath: string): Promise<void> => {
     process.exit(1);
   }
 
-  const lexResult = new Lexer(src).tokenize();
-  const parseResult = new Parser(lexResult.tokens).parse();
-
-  const errors = [...lexResult.errorMarkers, ...parseResult.errorMarkers];
-  if (errors.length > 0) {
-    for (const marker of errors) {
-      process.stderr.write(chalk.red(`[${marker.code}]`) + '\n');
-    }
-    process.exit(1);
-  }
-
-  if (parseResult.program === null) return;
-
-  const typeResult = typecheck(parseResult.program);
-  if (typeResult.errorMarkers.length > 0) {
-    for (const marker of typeResult.errorMarkers) {
-      process.stderr.write(chalk.red(`[${marker.code}]`) + '\n');
+  const parseResult = parse(src);
+  if (parseResult.errorMarkers.length > 0) {
+    for (const marker of parseResult.errorMarkers) {
+      process.stderr.write(renderTerminal(elaborate(marker, src), src, filePath) + '\n\n');
     }
     process.exit(1);
   }
 
+  const typedProgram = parseResult.typedProgram!;
   const env = new Environment();
-  if (parseResult.program.args.length > 0) {
-    bindArgs(parseResult.program.args, parseCliFlags(process.argv.slice(3)), env);
+  if (typedProgram.args.length > 0) {
+    bindArgs(typedProgram.args, parseCliFlags(process.argv.slice(3)), env);
   }
 
   try {
-    const result = executeProgram(typeResult.typedProgram!, env);
+    const result = executeProgram(typedProgram, env);
     if (result.type !== 'Done') {
       process.stdout.write(formatValue(result) + '\n');
     }
@@ -155,19 +145,19 @@ const runRepl = async (): Promise<void> => {
 
       process.stdout.write(tokenParts.join(`  ${chalk.dim('·')}  `) + '\n');
 
-      const parseResult = new Parser(lexResult.tokens).parse();
+      const parseResult = parseTokens(lexResult.tokens);
 
       // A non-null program no longer means error-free: panic-mode
       // 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 +165,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.