cashc 0.13.0 → 0.13.2

package/dist/Errors.d.ts

@@ -1,13 +1,14 @@
 import { Type } from '@cashscript/utils';
 import { IdentifierNode, FunctionDefinitionNode, VariableDefinitionNode, ParameterNode, Node, FunctionCallNode, BinaryOpNode, UnaryOpNode, TimeOpNode, CastNode, AssignNode, BranchNode, ArrayNode, TupleIndexOpNode, RequireNode, InstantiationNode, StatementNode, ContractNode, ExpressionNode, SliceNode } from './ast/AST.js';
 import { Symbol, SymbolType } from './ast/SymbolTable.js';
-import { Location, Point } from './ast/Location.js';
+import { Location } from './ast/Location.js';
 export declare class CashScriptError extends Error {
     node: Node;
     constructor(node: Node, message: string);
 }
 export declare class ParseError extends Error {
-    constructor(message: string, location?: Point | Location);
+    location: Location;
+    constructor(message: string, location: Location);
 }
 export declare class UndefinedReferenceError extends CashScriptError {
     node: IdentifierNode;

package/dist/Errors.js

@@ -1,6 +1,5 @@
 import { PrimitiveType } from '@cashscript/utils';
 import { BinaryOpNode, UnaryOpNode, TimeOpNode, AssignNode, TupleIndexOpNode, RequireNode, SliceNode, IntLiteralNode, } from './ast/AST.js';
-import { Point } from './ast/Location.js';
 import { BinaryOperator } from './ast/Operator.js';
 export class CashScriptError extends Error {
     constructor(node, message) {
@@ -14,12 +13,11 @@ export class CashScriptError extends Error {
 }
 export class ParseError extends Error {
     constructor(message, location) {
-        const start = location instanceof Point ? location : location?.start;
-        if (start) {
-            message += ` at ${start}`;
-        }
+        message += ` at ${location.start}`;
         super(message);
+        this.location = location;
         this.name = this.constructor.name;
+        this.location = location;
     }
 }
 export class UndefinedReferenceError extends CashScriptError {

package/dist/ast/error-listeners.d.ts

@@ -0,0 +1,22 @@
+import { ErrorListener, RecognitionException, Recognizer } from 'antlr4';
+export interface CashScriptErrorListener {
+    syntaxError(recognizer: unknown, offendingSymbol: unknown, line: number, charPositionInLine: number, message: string, e?: unknown): void;
+}
+/**
+ * Error listener that forwards syntax errors to another listener and stores the first error.
+ */
+export declare class ForwardingErrorListener extends ErrorListener<unknown> implements CashScriptErrorListener {
+    private readonly errorListener;
+    private firstError?;
+    constructor(errorListener: CashScriptErrorListener);
+    syntaxError(recognizer: unknown, offendingSymbol: unknown, line: number, charPositionInLine: number, message: string, e?: unknown): void;
+    throwFirstError(): void;
+}
+/**
+ * ANTLR Error Listener that immediately throws on error. This is used so that
+ * ANTLR doesn't attempt any error recovery during lexing/parsing and fails early.
+ */
+export declare class ThrowingErrorListener<TSymbol> extends ErrorListener<TSymbol> {
+    static readonly INSTANCE: ThrowingErrorListener<unknown>;
+    syntaxError(_recognizer: Recognizer<TSymbol>, offendingSymbol: TSymbol, line: number, charPositionInLine: number, message: string, _e?: RecognitionException): void;
+}

package/dist/ast/error-listeners.js

@@ -0,0 +1,91 @@
+import { ErrorListener, Token } from 'antlr4';
+import { ParseError } from '../Errors.js';
+import { Location, Point } from './Location.js';
+/**
+ * Error listener that forwards syntax errors to another listener and stores the first error.
+ */
+export class ForwardingErrorListener extends ErrorListener {
+    constructor(errorListener) {
+        super();
+        this.errorListener = errorListener;
+    }
+    syntaxError(recognizer, offendingSymbol, line, charPositionInLine, message, e) {
+        const normalisedMessage = normaliseSyntaxErrorMessage(message, offendingSymbol);
+        this.firstError ??= createParseError(line, charPositionInLine, normalisedMessage, offendingSymbol);
+        this.errorListener.syntaxError(recognizer, offendingSymbol, line, charPositionInLine, normalisedMessage, e);
+    }
+    throwFirstError() {
+        if (this.firstError)
+            throw this.firstError;
+    }
+}
+/**
+ * ANTLR Error Listener that immediately throws on error. This is used so that
+ * ANTLR doesn't attempt any error recovery during lexing/parsing and fails early.
+ */
+export class ThrowingErrorListener extends ErrorListener {
+    syntaxError(_recognizer, offendingSymbol, line, charPositionInLine, message, _e) {
+        const normalisedMessage = normaliseSyntaxErrorMessage(message, offendingSymbol);
+        throw createParseError(line, charPositionInLine, normalisedMessage, offendingSymbol);
+    }
+}
+ThrowingErrorListener.INSTANCE = new ThrowingErrorListener();
+function createParseError(line, charPositionInLine, message, offendingSymbol) {
+    const capitalisedMessage = message.charAt(0).toUpperCase() + message.slice(1);
+    const token = getToken(offendingSymbol);
+    const location = getTokenLocation(token) ?? createEmptyLocation(line, charPositionInLine);
+    return new ParseError(capitalisedMessage, location);
+}
+function normaliseSyntaxErrorMessage(message, offendingSymbol) {
+    const token = getToken(offendingSymbol);
+    const tokenText = getTokenText(token);
+    if (!tokenText)
+        return message;
+    // There are 2 common error messages that we need to normalise:
+    const noViableAlternativeInput = getNoViableAlternativeInput(message);
+    const extraneousInput = isExtraneousInput(message, tokenText);
+    if (isBoundedBytesExpressionError(message, tokenText, noViableAlternativeInput)) {
+        return boundedBytesCastMessage(tokenText);
+    }
+    if (noViableAlternativeInput !== undefined || extraneousInput) {
+        return `Unexpected token '${tokenText}'`;
+    }
+    return message;
+}
+function isBoundedBytesExpressionError(message, tokenText, noViableAlternativeInput) {
+    if (!isBoundedBytesToken(tokenText))
+        return false;
+    return noViableAlternativeInput?.includes(`(${tokenText}`) || isExtraneousInput(message, tokenText);
+}
+function isBoundedBytesToken(tokenText) {
+    return tokenText === 'byte' || /^bytes[1-9][0-9]*$/.test(tokenText);
+}
+function boundedBytesCastMessage(typeName) {
+    const bound = typeName === 'byte' ? 1 : Number(typeName.slice('bytes'.length));
+    const unsafeCast = typeName === 'byte' ? 'unsafe_byte' : `unsafe_${typeName}`;
+    return `Invalid bounded bytes cast '${typeName}(...)'. Use 'toPaddedBytes(value, ${bound})' to convert an int or '${unsafeCast}(value)' for semantic bytes casts`;
+}
+function getNoViableAlternativeInput(message) {
+    return message.match(/^no viable alternative at input '([\s\S]*)'$/)?.[1];
+}
+function isExtraneousInput(message, tokenText) {
+    return message.startsWith(`extraneous input '${tokenText}'`);
+}
+function getToken(offendingSymbol) {
+    return offendingSymbol instanceof Token ? offendingSymbol : undefined;
+}
+function getTokenText(token) {
+    if (!token || token.type === Token.EOF || typeof token.text !== 'string' || token.text === '<EOF>') {
+        return undefined;
+    }
+    return token.text;
+}
+function getTokenLocation(token) {
+    if (!token || !getTokenText(token))
+        return undefined;
+    return Location.fromToken(token);
+}
+function createEmptyLocation(line, column) {
+    return new Location(new Point(line, column), new Point(line, column));
+}
+//# sourceMappingURL=error-listeners.js.map

package/dist/compiler.d.ts

@@ -1,7 +1,11 @@
 import { Artifact, CompilerOptions } from '@cashscript/utils';
 import { PathLike } from 'fs';
 import { Ast } from './ast/AST.js';
+import { CashScriptErrorListener } from './ast/error-listeners.js';
 export declare const DEFAULT_COMPILER_OPTIONS: CompilerOptions;
+export interface CompileOptions extends CompilerOptions {
+    errorListener?: CashScriptErrorListener;
+}
 /**
  * Compile a CashScript source string to an {@link Artifact}.
  *
@@ -10,7 +14,7 @@ export declare const DEFAULT_COMPILER_OPTIONS: CompilerOptions;
  * @returns The compiled CashScript artifact, including ABI, bytecode and debug information.
  * @throws If the source code contains a syntax, semantic, or type error.
  */
-export declare function compileString(code: string, compilerOptions?: CompilerOptions): Artifact;
+export declare function compileString(code: string, compilerOptions?: CompileOptions): Artifact;
 /**
  * Read a `.cash` source file from disk and compile it to an `Artifact`.
  *
@@ -19,5 +23,5 @@ export declare function compileString(code: string, compilerOptions?: CompilerOp
  * @returns The compiled CashScript artifact.
  * @throws If the file cannot be read, or if the source contains a compilation error.
  */
-export declare function compileFile(codeFile: PathLike, compilerOptions?: CompilerOptions): Artifact;
-export declare function parseCode(code: string): Ast;
+export declare function compileFile(codeFile: PathLike, compilerOptions?: CompileOptions): Artifact;
+export declare function parseCode(code: string, errorListener?: CashScriptErrorListener): Ast;

package/dist/compiler.js

@@ -1,10 +1,10 @@
 import { CharStream, CommonTokenStream } from 'antlr4';
 import { binToHex } from '@bitauth/libauth';
-import { computeBytecodeFingerprintWithConstructorArgs, generateSourceMap, generateSourceTags, optimiseBytecode, optimiseBytecodeOld, scriptToAsm, scriptToBytecode, sourceMapToLocationData } from '@cashscript/utils';
+import { computeBytecodeFingerprintWithConstructorArgs, generateSourceMap, generateSourceTags, optimiseBytecode, optimiseBytecodeOld, scriptToAsm, scriptToBytecode, sourceMapToLocationData, } from '@cashscript/utils';
 import fs from 'fs';
 import { generateArtifact } from './artifact/Artifact.js';
 import AstBuilder from './ast/AstBuilder.js';
-import ThrowingErrorListener from './ast/ThrowingErrorListener.js';
+import { ThrowingErrorListener, ForwardingErrorListener } from './ast/error-listeners.js';
 import GenerateTargetTraversal from './generation/GenerateTargetTraversal.js';
 import CashScriptLexer from './grammar/CashScriptLexer.js';
 import CashScriptParser from './grammar/CashScriptParser.js';
@@ -25,9 +25,10 @@ export const DEFAULT_COMPILER_OPTIONS = {
  * @throws If the source code contains a syntax, semantic, or type error.
  */
 export function compileString(code, compilerOptions = {}) {
-    const mergedCompilerOptions = { ...DEFAULT_COMPILER_OPTIONS, ...compilerOptions };
+    const { errorListener, ...artifactCompilerOptions } = compilerOptions;
+    const mergedCompilerOptions = { ...DEFAULT_COMPILER_OPTIONS, ...artifactCompilerOptions };
     // Lexing + parsing
-    let ast = parseCode(code);
+    let ast = parseCode(code, errorListener);
     // Semantic analysis
     ast = ast.accept(new SymbolTableTraversal());
     ast = ast.accept(new TypeCheckTraversal());
@@ -71,18 +72,20 @@ export function compileFile(codeFile, compilerOptions = {}) {
     const code = fs.readFileSync(codeFile, { encoding: 'utf-8' });
     return compileString(code, compilerOptions);
 }
-export function parseCode(code) {
+export function parseCode(code, errorListener = ThrowingErrorListener.INSTANCE) {
+    const syntaxErrorListener = new ForwardingErrorListener(errorListener);
     // Lexing (throwing on errors)
     const inputStream = new CharStream(code);
     const lexer = new CashScriptLexer(inputStream);
     lexer.removeErrorListeners();
-    lexer.addErrorListener(ThrowingErrorListener.INSTANCE);
+    lexer.addErrorListener(syntaxErrorListener);
     const tokenStream = new CommonTokenStream(lexer);
     // Parsing (throwing on errors)
     const parser = new CashScriptParser(tokenStream);
     parser.removeErrorListeners();
-    parser.addErrorListener(ThrowingErrorListener.INSTANCE);
+    parser.addErrorListener(syntaxErrorListener);
     const parseTree = parser.sourceFile();
+    syntaxErrorListener.throwFirstError();
     // AST building
     const ast = new AstBuilder(parseTree).build();
     return ast;

package/dist/generation/GenerateTargetTraversal.d.ts

@@ -42,7 +42,9 @@ export default class GenerateTargetTraversalWithLocation extends AstTraversal {
     visitDoWhile(node: DoWhileNode): Node;
     visitWhile(node: WhileNode): Node;
     visitFor(node: ForNode): Node;
+    private emitLoopCondition;
     removeScopedVariables(depthBeforeScope: number, node: Node): void;
+    private tagScopeCleanup;
     visitCast(node: CastNode): Node;
     visitFunctionCall(node: FunctionCallNode): Node;
     visitMultiSig(node: FunctionCallNode): Node;

package/dist/generation/GenerateTargetTraversal.js

@@ -151,11 +151,13 @@ export default class GenerateTargetTraversalWithLocation extends AstTraversal {
     }
     cleanStack(functionBodyNode) {
         // Keep final verification value, OP_NIP the other stack values
+        const tagStartIndex = this.output.length;
         const stackSize = this.stack.length;
         for (let i = 0; i < stackSize - 1; i += 1) {
             this.emit(Op.OP_NIP, { location: functionBodyNode.location, positionHint: PositionHint.END });
             this.nipFromStack();
         }
+        this.tagScopeCleanup(tagStartIndex);
     }
     enforceFunctionParameterTypes(node) {
         node.parameters.forEach((parameter) => this.enforceFunctionParameterType(parameter));
@@ -349,12 +351,7 @@ export default class GenerateTargetTraversalWithLocation extends AstTraversal {
         const bodyStackDepth = this.stack.length;
         node.block = this.visit(node.block);
         this.removeScopedVariables(bodyStackDepth, node.block);
-        this.emit(Op.OP_ENDIF, { location: node.block.location, positionHint: PositionHint.END });
-        this.emit(Op.OP_FROMALTSTACK, { location: node.block.location, positionHint: PositionHint.END });
-        this.pushToStack('(value)');
-        this.emit(Op.OP_NOT, { location: node.location, positionHint: PositionHint.END });
-        this.emit(Op.OP_UNTIL, { location: node.location, positionHint: PositionHint.END });
-        this.popFromStack();
+        this.emitLoopCondition(node);
         this.scopeDepth -= 1;
         return node;
     }
@@ -377,22 +374,46 @@ export default class GenerateTargetTraversalWithLocation extends AstTraversal {
         const updateEndIndex = this.output.length - 1;
         this.sourceTags.push({ startIndex: updateStartIndex, endIndex: updateEndIndex, kind: SourceTagKind.FOR_UPDATE });
         this.removeScopedVariables(bodyStackDepth, node.block);
+        this.emitLoopCondition(node);
+        this.scopeDepth -= 1;
+        this.removeScopedVariables(forScopeStackDepth, node);
+        return node;
+    }
+    // Emits the loop-back epilogue shared by while- and for-loops: OP_ENDIF closes the body branch,
+    // then OP_FROMALTSTACK OP_NOT OP_UNTIL re-checks the saved condition and jumps back. These are
+    // compiler-injected and map to the closing brace; tag them so the debug reconstruction renders a
+    // ">>> loop condition check" annotation line (and the following loop-variable cleanup) before the brace.
+    emitLoopCondition(node) {
+        const tagStartIndex = this.output.length;
         this.emit(Op.OP_ENDIF, { location: node.block.location, positionHint: PositionHint.END });
         this.emit(Op.OP_FROMALTSTACK, { location: node.block.location, positionHint: PositionHint.END });
         this.pushToStack('(value)');
         this.emit(Op.OP_NOT, { location: node.location, positionHint: PositionHint.END });
         this.emit(Op.OP_UNTIL, { location: node.location, positionHint: PositionHint.END });
         this.popFromStack();
-        this.scopeDepth -= 1;
-        this.removeScopedVariables(forScopeStackDepth, node);
-        return node;
+        this.sourceTags.push({
+            startIndex: tagStartIndex,
+            endIndex: this.output.length - 1,
+            kind: SourceTagKind.LOOP_CONDITION,
+        });
     }
     removeScopedVariables(depthBeforeScope, node) {
+        const tagStartIndex = this.output.length;
         const dropCount = this.stack.length - depthBeforeScope;
         for (let i = 0; i < dropCount; i += 1) {
             this.emit(Op.OP_DROP, { location: node.location, positionHint: PositionHint.END });
             this.popFromStack();
         }
+        this.tagScopeCleanup(tagStartIndex);
+    }
+    tagScopeCleanup(tagStartIndex) {
+        if (this.output.length <= tagStartIndex)
+            return;
+        this.sourceTags.push({
+            startIndex: tagStartIndex,
+            endIndex: this.output.length - 1,
+            kind: SourceTagKind.SCOPE_CLEANUP,
+        });
     }
     visitCast(node) {
         node.expression = this.visit(node.expression);

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export * from './Errors.js';
 export * as utils from '@cashscript/utils';
-export { compileFile, compileString } from './compiler.js';
-export declare const version = "0.13.0";
+export { compileFile, compileString, type CompileOptions } from './compiler.js';
+export * from './ast/Location.js';
+export * from './ast/error-listeners.js';
+export declare const version = "0.13.2";

package/dist/index.js

@@ -1,5 +1,7 @@
 export * from './Errors.js';
 export * as utils from '@cashscript/utils';
 export { compileFile, compileString } from './compiler.js';
-export const version = '0.13.0';
+export * from './ast/Location.js';
+export * from './ast/error-listeners.js';
+export const version = '0.13.2';
 //# sourceMappingURL=index.js.map

package/dist/semantic/SymbolTableTraversal.js

@@ -94,11 +94,13 @@ export default class SymbolTableTraversal extends AstTraversal {
         return node;
     }
     visitTupleAssignment(node) {
-        [node.left, node.right].forEach(({ name, type }) => {
+        [node.left, node.right].forEach((variable) => {
+            const definition = createTupleVariableDefinition(node, variable);
+            const { name } = variable;
             if (this.symbolTables[0].get(name)) {
-                throw new VariableRedefinitionError(new VariableDefinitionNode(type, [], name, node.tuple));
+                throw new VariableRedefinitionError(definition);
             }
-            this.symbolTables[0].set(Symbol.variable(new VariableDefinitionNode(type, [], name, node.tuple)));
+            this.symbolTables[0].set(Symbol.variable(definition));
         });
         node.tuple = this.visit(node.tuple);
         return node;
@@ -141,4 +143,9 @@ export default class SymbolTableTraversal extends AstTraversal {
         return node;
     }
 }
+function createTupleVariableDefinition(node, variable) {
+    const definition = new VariableDefinitionNode(variable.type, [], variable.name, node.tuple);
+    definition.location = node.location;
+    return definition;
+}
 //# sourceMappingURL=SymbolTableTraversal.js.map

package/dist/semantic/TypeCheckTraversal.js

@@ -18,7 +18,9 @@ export default class TypeCheckTraversal extends AstTraversal {
         }
         const assignmentType = new TupleType(node.left.type, node.right.type);
         if (!implicitlyCastable(node.tuple.type, assignmentType)) {
-            throw new AssignTypeError(new VariableDefinitionNode(assignmentType, [], node.left.name, node.tuple));
+            const syntheticAssignment = new VariableDefinitionNode(assignmentType, [], node.left.name, node.tuple);
+            syntheticAssignment.location = node.location;
+            throw new AssignTypeError(syntheticAssignment);
         }
         return node;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cashc",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "description": "Compile Bitcoin Cash contracts to Bitcoin Cash Script or artifacts",
   "keywords": [
     "bitcoin",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@bitauth/libauth": "^3.1.0-next.8",
-    "@cashscript/utils": "^0.13.0",
+    "@cashscript/utils": "^0.13.2",
     "antlr4": "^4.13.2",
     "commander": "^14.0.0",
     "semver": "^7.7.2"
@@ -64,5 +64,5 @@
     "typescript": "^5.9.2",
     "vitest": "^4.0.15"
   },
-  "gitHead": "a3461662016a2f3dad36431ba5a2b148bcc4dc75"
+  "gitHead": "a4f112abb0d035ecf018ebc694e2b081f25b3409"
 }

package/dist/ast/ThrowingErrorListener.d.ts

@@ -1,9 +0,0 @@
-import { ErrorListener, RecognitionException, Recognizer } from 'antlr4';
-/**
- * ANTLR Error Listener that immediately throws on error. This is used so that
- * ANTLR doesn't attempt any error recovery during lexing/parsing and fails early.
- */
-export default class ThrowingErrorListener<TSymbol> extends ErrorListener<TSymbol> {
-    static readonly INSTANCE: ThrowingErrorListener<unknown>;
-    syntaxError(recognizer: Recognizer<TSymbol>, offendingSymbol: TSymbol, line: number, charPositionInLine: number, message: string, e?: RecognitionException): void;
-}

package/dist/ast/ThrowingErrorListener.js

@@ -1,17 +0,0 @@
-/* eslint-disable @typescript-eslint/no-unused-vars */
-import { ErrorListener } from 'antlr4';
-import { ParseError } from '../Errors.js';
-import { Point } from './Location.js';
-/**
- * ANTLR Error Listener that immediately throws on error. This is used so that
- * ANTLR doesn't attempt any error recovery during lexing/parsing and fails early.
- */
-class ThrowingErrorListener extends ErrorListener {
-    syntaxError(recognizer, offendingSymbol, line, charPositionInLine, message, e) {
-        const capitalisedMessage = message.charAt(0).toUpperCase() + message.slice(1);
-        throw new ParseError(capitalisedMessage, new Point(line, charPositionInLine));
-    }
-}
-ThrowingErrorListener.INSTANCE = new ThrowingErrorListener();
-export default ThrowingErrorListener;
-//# sourceMappingURL=ThrowingErrorListener.js.map