@aster-cloud/aster-lang-ts 1.2.5 → 1.2.6

package/dist/src/parser/expr-stmt-parser.js

@@ -7,6 +7,7 @@ import { parseType, parseEffectList } from './type-parser.js';
 import { parseConstraints } from './constraint-parser.js';
 import { inferFieldType, refineInferredType } from './type-inference.js';
 import { assignSpan, cloneSpan, lastNonLayoutToken, spanFromSources, spanFromTokens, } from './span-utils.js';
+import { Issue, kwParam, lit, tokenLit, tokenName } from './parse-issue.js';
 const WAIT_FOR_PARTS = kwParts(KW.WAIT_FOR);
 const MAX_ATTEMPTS_PARTS = kwParts(KW.MAX_ATTEMPTS);
 function peekKeywordIgnoringLayout(ctx, startIndex = ctx.index) {
@@ -43,28 +44,31 @@ const SUGAR_OUTCOMES = new Map([
     [`${KW.ESCALATE} _`, 'Verdict.escalate'],
     [`${KW.REQUIRE_APPROVAL_BY} _ ${KW.BECAUSE} _`, 'Verdict.require_approval'],
 ]);
-const SUGAR_OUTCOME_ERROR = 'Expected allow, deny, escalate or require approval by … because … after When/Otherwise';
-const OTHERWISE_NOT_LAST = 'Otherwise must be the last statement of its block';
+const SUGAR_OUTCOME_ERROR = Issue.expectedAfter(tokenName('verdictOutcome'), tokenName('whenOrOtherwise'), 'Expected allow, deny, escalate or require approval by … because … after When/Otherwise');
+const OTHERWISE_NOT_LAST = Issue.misplaced(kwParam(KW.OTHERWISE), tokenName('lastInBlock'), 'Otherwise must be the last statement of its block');
 /**
  * 块内语句解析器，错误次序对齐 Java AstBuilder：先查本块的 Otherwise 收尾（requireOtherwiseLast），
  * 再校验各语句的语法糖结论。因此 Otherwise 之后再有语句立即报错；本块结论非法的错误先记下，
  * 由 finish 在块结束时报出（只报第一条）。状态都在本块闭包里，随块解析结束而释放。
  */
 function blockStatementParser(ctx, error, statements) {
-    let closed = false;
+    // Otherwise 收尾的位置：其后再有语句时错误落在该 Otherwise 上（与 Java requireOtherwiseLast 一致）
+    let closedBy;
+    // 记下 token：错误落在结论起点（与 Java AstBuilder 报在 sugarOutcome 上下文一致），而非块末
     let pendingOutcomeError;
-    const deferOutcomeError = (msg) => { pendingOutcomeError ??= msg; };
+    const deferOutcomeError = (issue, tok) => { pendingOutcomeError ??= { issue, tok }; };
     return {
         next: () => {
-            if (closed)
-                error(OTHERWISE_NOT_LAST);
+            if (closedBy !== undefined)
+                error(OTHERWISE_NOT_LAST, closedBy);
             // 语句开头的 Otherwise/else 必走 parseOtherwiseSugar（If 的 else 分支由 If 自身消费）
-            closed = isElseWord(ctx);
+            if (isElseWord(ctx))
+                closedBy = ctx.peek();
             statements.push(parseStatement(ctx, error, deferOutcomeError));
         },
         finish: () => {
             if (pendingOutcomeError !== undefined)
-                error(pendingOutcomeError);
+                error(pendingOutcomeError.issue, pendingOutcomeError.tok);
         },
     };
 }
@@ -91,7 +95,7 @@ export function parseBlock(ctx, error) {
             ctx.consumeNewlines();
         }
         if (!ctx.at(TokenKind.DEDENT))
-            error('Expected dedent');
+            error(Issue.expected(tokenName('dedent'), 'Expected dedent'));
         blockParser.finish();
         const endTok = ctx.peek();
         ctx.next();
@@ -118,7 +122,7 @@ export function parseBlock(ctx, error) {
             ctx.consumeNewlines();
         }
         if (statements.length === 0)
-            error('Expected at least one statement in function body');
+            error(Issue.emptyBlock(tokenName('functionBody'), tokenName('statement'), 'Expected at least one statement in function body'));
         blockParser.finish();
         const endTok = ctx.tokens[ctx.index - 1] || startTok;
         const b = Node.Block(statements);
@@ -151,9 +155,9 @@ export function parseExplicitBlock(ctx, error) {
         ctx.consumeNewlines();
     }
     if (!ctx.at(TokenKind.BLOCK_END))
-        error("Expected explicit block end word (e.g. '毕')");
+        error(Issue.expected(tokenName('blockEndWord'), "Expected explicit block end word (e.g. '毕')"));
     if (statements.length === 0)
-        error('Expected at least one statement in explicit block');
+        error(Issue.emptyBlock(tokenName('explicitBlock'), tokenName('statement'), 'Expected at least one statement in explicit block'));
     blockParser.finish();
     ctx.next(); // consume BLOCK_END
     const b = Node.Block(statements);
@@ -169,7 +173,7 @@ export function parseExplicitBlock(ctx, error) {
  */
 function expectPeriodEnd(ctx, error) {
     if (!ctx.at(TokenKind.DOT))
-        error("Expected '.' at end of statement");
+        error(Issue.expectedStatementEnd(lit('.'), "Expected '.' at end of statement"));
     ctx.next();
 }
 /**
@@ -212,11 +216,11 @@ function skipInlineElseLayout(ctx) {
 function parseInlineIf(ctx, error, cond) {
     skipInlineThenLayout(ctx);
     if (!ctx.isKeyword(KW.THEN))
-        error(`Expected ${kwq(ctx, KW.THEN)} in inline if`);
+        error(Issue.expectedIn(kwParam(KW.THEN), tokenName('inlineIf'), `Expected ${kwq(ctx, KW.THEN)} in inline if`));
     ctx.nextWord();
     // then 分支：单个 return（内联，不带句点；句点由整条 inline-if 末尾的 return 承担）。
     if (!ctx.isKeyword(KW.RETURN))
-        error(`Expected ${kwq(ctx, KW.RETURN)} after ${kwq(ctx, KW.THEN)}`);
+        error(Issue.expectedAfter(kwParam(KW.RETURN), kwParam(KW.THEN), `Expected ${kwq(ctx, KW.RETURN)} after ${kwq(ctx, KW.THEN)}`));
     const thenRetTok = ctx.peek();
     ctx.nextWord();
     const thenExpr = parseExpr(ctx, error);
@@ -245,7 +249,7 @@ function parseInlineIf(ctx, error, cond) {
         else {
             // else return X.（末尾 return，带句点）。
             if (!ctx.isKeyword(KW.RETURN))
-                error(`Expected ${kwq(ctx, KW.RETURN)} or ${kwq(ctx, KW.IF)} after ${kwKindq(ctx, SemanticTokenKind.OTHERWISE, 'else')}`);
+                error(Issue.expectedAfter(tokenName('returnOrIf'), kwParam(KW.OTHERWISE), `Expected ${kwq(ctx, KW.RETURN)} or ${kwq(ctx, KW.IF)} after ${kwKindq(ctx, SemanticTokenKind.OTHERWISE, 'else')}`));
             const elseRetTok = ctx.peek();
             ctx.nextWord();
             const elseExpr = parseExpr(ctx, error);
@@ -293,7 +297,7 @@ function parseSugarOutcome(ctx, error, reportOutcomeError) {
     const startTok = ctx.peek();
     const badStart = OUTCOME_BAD_START.get(startTok.kind);
     if (badStart !== undefined)
-        error(`Unexpected '${badStart}' where an outcome was expected`);
+        error(Issue.unexpected(lit(badStart), `Unexpected '${badStart}' where an outcome was expected`));
     const shape = [];
     const args = [];
     for (let tok = ctx.peek(); !OUTCOME_END.has(tok.kind); tok = ctx.peek()) {
@@ -309,7 +313,7 @@ function parseSugarOutcome(ctx, error, reportOutcomeError) {
     // 查表落空时 target 为空串：错误若被延后，整次解析终将失败，该节点不会流出
     const target = SUGAR_OUTCOMES.get(shape.join(' ')) ?? '';
     if (target === '')
-        reportOutcomeError(SUGAR_OUTCOME_ERROR);
+        reportOutcomeError(SUGAR_OUTCOME_ERROR, startTok);
     // 与 Java 一致：合成的 Name/Call/Return 共用结论词范围（不含句点）
     const span = spanFromTokens(startTok, lastNonLayoutToken(ctx));
     const call = assignSpan(Node.Call(assignSpan(Node.Name(target), span), args), span);
@@ -320,7 +324,7 @@ function parseWhenSugar(ctx, error, reportOutcomeError) {
     const whenTok = ctx.nextWord();
     const cond = parseExpr(ctx, error);
     if (!ctx.at(TokenKind.COMMA))
-        error("Expected ',' after When condition");
+        error(Issue.expectedAfter(lit(','), tokenName('whenCondition'), "Expected ',' after When condition"));
     ctx.next();
     const ret = parseSugarOutcome(ctx, error, reportOutcomeError);
     expectPeriodEnd(ctx, error);
@@ -346,7 +350,7 @@ export function parseStatement(ctx, error, reportOutcomeError = error) {
         ctx.nextWord();
         const nameTok = ctx.peek();
         const name = parseIdent(ctx, error);
-        expectKeyword(ctx, error, KW.BE, `Use ${kwq(ctx, KW.BE)} in bindings: '${kw(ctx, KW.LET, 'Let')} x ${kw(ctx, KW.BE)} ...'.`);
+        expectKeyword(ctx, error, KW.BE, Issue.expectedIn(kwParam(KW.BE), tokenName('binding'), `Use ${kwq(ctx, KW.BE)} in bindings: '${kw(ctx, KW.LET, 'Let')} x ${kw(ctx, KW.BE)} ...'.`));
         // Special-case lambda block form to avoid trailing '.'
         if ((ctx.isKeyword('a') && tokLowerAt(ctx, ctx.index + 1) === 'function') || ctx.isKeyword('function')) {
             if (ctx.isKeyword('a'))
@@ -354,7 +358,7 @@ export function parseStatement(ctx, error, reportOutcomeError = error) {
             const functionTok = ctx.nextWord(); // 'function'
             const params = parseParamList(ctx, error);
             expectCommaOr(ctx);
-            expectKeyword(ctx, error, KW.PRODUCE, `Expected ${kwq(ctx, KW.PRODUCE)} and return type`);
+            expectKeyword(ctx, error, KW.PRODUCE, Issue.expected(kwParam(KW.PRODUCE), `Expected ${kwq(ctx, KW.PRODUCE)} and return type`));
             let retType;
             if (ctx.at(TokenKind.COLON)) {
                 retType = Node.TypeName('Unknown');
@@ -364,7 +368,7 @@ export function parseStatement(ctx, error, reportOutcomeError = error) {
                 retType = parseType(ctx, error);
             }
             if (!ctx.at(TokenKind.COLON))
-                error("Expected ':' after return type in lambda");
+                error(Issue.expectedAfterIn(lit(':'), tokenName('returnType'), tokenName('lambda'), "Expected ':' after return type in lambda"));
             ctx.next();
             expectNewline(ctx, error);
             const body = parseBlock(ctx, error);
@@ -390,7 +394,7 @@ export function parseStatement(ctx, error, reportOutcomeError = error) {
         const setTok = ctx.peek();
         ctx.nextWord();
         const name = parseIdent(ctx, error);
-        expectKeyword(ctx, error, KW.TO_WORD, `Use ${kwq(ctx, KW.TO_WORD)} in assignments: '${kw(ctx, KW.SET, 'Set')} x ${kw(ctx, KW.TO_WORD)} ...'.`);
+        expectKeyword(ctx, error, KW.TO_WORD, Issue.expectedIn(kwParam(KW.TO_WORD), tokenName('assignment'), `Use ${kwq(ctx, KW.TO_WORD)} in assignments: '${kw(ctx, KW.SET, 'Set')} x ${kw(ctx, KW.TO_WORD)} ...'.`));
         const expr = parseExpr(ctx, error);
         expectPeriodEnd(ctx, error);
         const nd = Node.Set(name, expr);
@@ -425,10 +429,10 @@ export function parseStatement(ctx, error, reportOutcomeError = error) {
     if (ctx.isKeyword(KW.AWAIT)) {
         const awaitTok = ctx.nextWord();
         if (!ctx.at(TokenKind.LPAREN))
-            error("Expected '(' after await");
+            error(Issue.expectedAfter(lit('('), lit('await'), "Expected '(' after await"));
         const args = parseArgList(ctx, error);
         if (args.length !== 1)
-            error('await(expr) takes exactly one argument');
+            error(Issue.callArity(lit('await'), 1, args.length, 'await(expr) takes exactly one argument'));
         const target = assignTokenSpan(Node.Name('await'), awaitTok);
         const callSpanEnd = lastNonLayoutToken(ctx);
         const aw = Node.Call(target, args);
@@ -476,7 +480,7 @@ export function parseStatement(ctx, error, reportOutcomeError = error) {
         ctx.nextWord();
         const expr = parseExpr(ctx, error);
         if (!ctx.at(TokenKind.COLON))
-            error("Expected ':' after match expression");
+            error(Issue.expectedAfter(lit(':'), tokenName('matchExpression'), "Expected ':' after match expression"));
         ctx.next();
         expectNewline(ctx, error);
         const cases = parseCases(ctx, error);
@@ -509,9 +513,9 @@ export function parseStatement(ctx, error, reportOutcomeError = error) {
     }
     if (ctx.isKeyword(KW.WITHIN)) {
         ctx.nextWord();
-        expectKeyword(ctx, error, KW.SCOPE, `Expected ${kwq(ctx, KW.SCOPE)} after ${kwq(ctx, KW.WITHIN, 'Within')}`);
+        expectKeyword(ctx, error, KW.SCOPE, Issue.expectedAfter(kwParam(KW.SCOPE), kwParam(KW.WITHIN), `Expected ${kwq(ctx, KW.SCOPE)} after ${kwq(ctx, KW.WITHIN, 'Within')}`));
         if (!ctx.at(TokenKind.COLON))
-            error(`Expected ':' after ${kwq(ctx, KW.SCOPE)}`);
+            error(Issue.expectedAfter(lit(':'), kwParam(KW.SCOPE), `Expected ':' after ${kwq(ctx, KW.SCOPE)}`));
         ctx.next();
         expectNewline(ctx, error);
         return parseBlock(ctx, error); // Lowering later
@@ -519,8 +523,8 @@ export function parseStatement(ctx, error, reportOutcomeError = error) {
     if (ctx.isKeyword(KW.START)) {
         const startTok = ctx.nextWord();
         const name = parseIdent(ctx, error);
-        expectKeyword(ctx, error, KW.AS, `Expected ${kwq(ctx, KW.AS)} after name`);
-        expectKeyword(ctx, error, KW.ASYNC, `Expected ${kwq(ctx, KW.ASYNC)}`);
+        expectKeyword(ctx, error, KW.AS, Issue.expectedAfter(kwParam(KW.AS), tokenName('name'), `Expected ${kwq(ctx, KW.AS)} after name`));
+        expectKeyword(ctx, error, KW.ASYNC, Issue.expected(kwParam(KW.ASYNC), `Expected ${kwq(ctx, KW.ASYNC)}`));
         const expr = parseExpr(ctx, error);
         expectPeriodEnd(ctx, error);
         const nd = Node.Start(name, expr);
@@ -549,17 +553,17 @@ export function parseStatement(ctx, error, reportOutcomeError = error) {
         assignSpan(nd, spanFromTokens(waitStart, endTok));
         return nd;
     }
-    error('Unknown statement');
+    error(Issue.unexpectedConstruct(tokenName('statement'), 'Unknown statement'));
 }
 function parseWorkflow(ctx, error) {
     const workflowTok = ctx.peek();
-    expectKeyword(ctx, error, KW.WORKFLOW, `Expected ${kwq(ctx, KW.WORKFLOW)}`);
+    expectKeyword(ctx, error, KW.WORKFLOW, Issue.expected(kwParam(KW.WORKFLOW), `Expected ${kwq(ctx, KW.WORKFLOW)}`));
     if (!ctx.at(TokenKind.COLON))
-        error(`Expected ':' after ${kwq(ctx, KW.WORKFLOW)}`);
+        error(Issue.expectedAfter(lit(':'), kwParam(KW.WORKFLOW), `Expected ':' after ${kwq(ctx, KW.WORKFLOW)}`));
     ctx.next();
     expectNewline(ctx, error);
     if (!ctx.at(TokenKind.INDENT))
-        error('Expected indent after workflow header');
+        error(Issue.expectedAfter(tokenName('indent'), tokenName('workflowHeader'), 'Expected indent after workflow header'));
     ctx.next();
     ctx.consumeNewlines();
     const steps = [];
@@ -568,7 +572,7 @@ function parseWorkflow(ctx, error) {
         ctx.consumeNewlines();
     }
     if (steps.length === 0)
-        error('Workflow must declare at least one step');
+        error(Issue.emptyBlock(kwParam(KW.WORKFLOW), kwParam(KW.STEP), 'Workflow must declare at least one step'));
     let retry;
     if (ctx.isKeyword(KW.RETRY)) {
         retry = parseRetryPolicy(ctx, error);
@@ -580,7 +584,7 @@ function parseWorkflow(ctx, error) {
         ctx.consumeNewlines();
     }
     if (!ctx.at(TokenKind.DEDENT))
-        error('Expected dedent after workflow body');
+        error(Issue.expectedAfter(tokenName('dedent'), tokenName('workflowBody'), 'Expected dedent after workflow body'));
     ctx.next();
     ctx.consumeNewlines();
     expectPeriodEnd(ctx, error);
@@ -591,19 +595,19 @@ function parseWorkflow(ctx, error) {
 }
 function parseStep(ctx, error) {
     const stepTok = ctx.peek();
-    expectKeyword(ctx, error, KW.STEP, `Expected ${kwq(ctx, KW.STEP)}`);
+    expectKeyword(ctx, error, KW.STEP, Issue.expected(kwParam(KW.STEP), `Expected ${kwq(ctx, KW.STEP)}`));
     const name = parseIdent(ctx, error);
     const dependencies = [];
     if (ctx.isKeyword(KW.DEPENDS)) {
         ctx.nextWord();
-        expectKeyword(ctx, error, KW.ON, `Expected ${kwq(ctx, KW.ON)} after ${kwq(ctx, KW.DEPENDS)}`);
+        expectKeyword(ctx, error, KW.ON, Issue.expectedAfter(kwParam(KW.ON), kwParam(KW.DEPENDS), `Expected ${kwq(ctx, KW.ON)} after ${kwq(ctx, KW.DEPENDS)}`));
         if (!ctx.at(TokenKind.LBRACKET))
-            error(`Expected '[' after '${kw(ctx, KW.DEPENDS)} ${kw(ctx, KW.ON)}'`);
+            error(Issue.expectedAfter(lit('['), kwParam(KW.DEPENDS), `Expected '[' after '${kw(ctx, KW.DEPENDS)} ${kw(ctx, KW.ON)}'`));
         ctx.next();
         if (!ctx.at(TokenKind.RBRACKET)) {
             while (true) {
                 if (!ctx.at(TokenKind.STRING))
-                    error('Expected string dependency name');
+                    error(Issue.expected(tokenName('dependencyName'), 'Expected string dependency name'));
                 const depTok = ctx.next();
                 dependencies.push(depTok.value);
                 if (ctx.at(TokenKind.COMMA)) {
@@ -613,15 +617,15 @@ function parseStep(ctx, error) {
                 if (ctx.at(TokenKind.RBRACKET)) {
                     break;
                 }
-                error("Expected ',' or ']' after dependency name");
+                error(Issue.expectedAfter(tokenName('commaOrCloseBracket'), tokenName('dependencyName'), "Expected ',' or ']' after dependency name"));
             }
         }
         if (!ctx.at(TokenKind.RBRACKET))
-            error("Expected ']' to close dependency list");
+            error(Issue.expectedIn(lit(']'), tokenName('dependencyList'), "Expected ']' to close dependency list"));
         ctx.next();
     }
     if (!ctx.at(TokenKind.COLON))
-        error("Expected ':' after step name");
+        error(Issue.expectedAfter(lit(':'), tokenName('stepName'), "Expected ':' after step name"));
     ctx.next();
     expectNewline(ctx, error);
     const body = parseBlock(ctx, error);
@@ -630,7 +634,7 @@ function parseStep(ctx, error) {
     if (ctx.isKeyword(KW.COMPENSATE)) {
         ctx.nextWord();
         if (!ctx.at(TokenKind.COLON))
-            error(`Expected ':' after ${kwq(ctx, KW.COMPENSATE)}`);
+            error(Issue.expectedAfter(lit(':'), kwParam(KW.COMPENSATE), `Expected ':' after ${kwq(ctx, KW.COMPENSATE)}`));
         ctx.next();
         expectNewline(ctx, error);
         compensate = parseBlock(ctx, error);
@@ -642,13 +646,15 @@ function parseStep(ctx, error) {
     return step;
 }
 function parseRetryPolicy(ctx, error) {
-    expectKeyword(ctx, error, KW.RETRY, `Expected ${kwq(ctx, KW.RETRY)}`);
+    // 缺必填指令的错误落在 retry 关键词上（与 Java AstBuilder 报在 retrySection 上一致），而非区块末尾
+    const retryTok = ctx.peek();
+    expectKeyword(ctx, error, KW.RETRY, Issue.expected(kwParam(KW.RETRY), `Expected ${kwq(ctx, KW.RETRY)}`));
     if (!ctx.at(TokenKind.COLON))
-        error(`Expected ':' after ${kwq(ctx, KW.RETRY)}`);
+        error(Issue.expectedAfter(lit(':'), kwParam(KW.RETRY), `Expected ':' after ${kwq(ctx, KW.RETRY)}`));
     ctx.next();
     expectNewline(ctx, error);
     if (!ctx.at(TokenKind.INDENT))
-        error('Expected indent for retry policy');
+        error(Issue.expectedIn(tokenName('indent'), tokenName('retryPolicy'), 'Expected indent for retry policy'));
     ctx.next();
     ctx.consumeNewlines();
     let maxAttempts = null;
@@ -657,56 +663,56 @@ function parseRetryPolicy(ctx, error) {
         if (ctx.isKeywordSeq(MAX_ATTEMPTS_PARTS)) {
             ctx.nextWords(MAX_ATTEMPTS_PARTS);
             if (!ctx.at(TokenKind.COLON))
-                error(`Expected ':' after ${kwq(ctx, KW.MAX_ATTEMPTS)}`);
+                error(Issue.expectedAfter(lit(':'), kwParam(KW.MAX_ATTEMPTS), `Expected ':' after ${kwq(ctx, KW.MAX_ATTEMPTS)}`));
             ctx.next();
             if (!ctx.at(TokenKind.INT))
-                error(`Expected integer after ${kwq(ctx, KW.MAX_ATTEMPTS)}`);
+                error(Issue.expectedAfter(tokenName('integer'), kwParam(KW.MAX_ATTEMPTS), `Expected integer after ${kwq(ctx, KW.MAX_ATTEMPTS)}`));
             const attempts = ctx.next().value;
             if (attempts <= 0)
-                error(`${kwq(ctx, KW.MAX_ATTEMPTS)} must be greater than zero`);
+                error(Issue.invalidValue(kwParam(KW.MAX_ATTEMPTS), attempts, tokenName('positiveInteger'), `${kwq(ctx, KW.MAX_ATTEMPTS)} must be greater than zero`));
             maxAttempts = attempts;
             expectPeriodEnd(ctx, error);
         }
         else if (ctx.isKeyword(KW.BACKOFF)) {
             ctx.nextWord();
             if (!ctx.at(TokenKind.COLON))
-                error(`Expected ':' after ${kwq(ctx, KW.BACKOFF)}`);
+                error(Issue.expectedAfter(lit(':'), kwParam(KW.BACKOFF), `Expected ':' after ${kwq(ctx, KW.BACKOFF)}`));
             ctx.next();
             const modeTok = ctx.nextWord();
             const mode = String(modeTok.value ?? '').toLowerCase();
             if (mode !== 'exponential' && mode !== 'linear') {
-                error("Backoff must be either 'exponential' or 'linear'");
+                error(Issue.invalidValue(kwParam(KW.BACKOFF), tokenLit(modeTok), tokenName('exponentialOrLinear'), "Backoff must be either 'exponential' or 'linear'"));
             }
             backoff = mode;
             expectPeriodEnd(ctx, error);
         }
         else {
-            error('Unknown retry directive');
+            error(Issue.unknownName(tokenName('retryDirective'), tokenLit(ctx.peek()), 'Unknown retry directive'));
         }
         ctx.consumeNewlines();
     }
     ctx.next();
     if (maxAttempts === null)
-        error(`Retry section must include ${kwq(ctx, KW.MAX_ATTEMPTS)}`);
+        error(Issue.emptyBlock(kwParam(KW.RETRY), kwParam(KW.MAX_ATTEMPTS), `Retry section must include ${kwq(ctx, KW.MAX_ATTEMPTS)}`), retryTok);
     if (backoff === null)
-        error(`Retry section must include ${kwq(ctx, KW.BACKOFF)}`);
+        error(Issue.emptyBlock(kwParam(KW.RETRY), kwParam(KW.BACKOFF), `Retry section must include ${kwq(ctx, KW.BACKOFF)}`), retryTok);
     return { maxAttempts, backoff };
 }
 function parseTimeout(ctx, error) {
-    expectKeyword(ctx, error, KW.TIMEOUT, `Expected ${kwq(ctx, KW.TIMEOUT)}`);
+    expectKeyword(ctx, error, KW.TIMEOUT, Issue.expected(kwParam(KW.TIMEOUT), `Expected ${kwq(ctx, KW.TIMEOUT)}`));
     if (!ctx.at(TokenKind.COLON))
-        error(`Expected ':' after ${kwq(ctx, KW.TIMEOUT)}`);
+        error(Issue.expectedAfter(lit(':'), kwParam(KW.TIMEOUT), `Expected ':' after ${kwq(ctx, KW.TIMEOUT)}`));
     ctx.next();
     if (!ctx.at(TokenKind.INT))
-        error('Expected integer timeout value');
+        error(Issue.expected(tokenName('timeoutInteger'), 'Expected integer timeout value'));
     const secondsTok = ctx.next();
     const seconds = secondsTok.value;
     if (seconds < 0)
-        error('Timeout value must be non-negative');
+        error(Issue.invalidValue(kwParam(KW.TIMEOUT), seconds, tokenName('nonNegativeInteger'), 'Timeout value must be non-negative'));
     if (!(ctx.isKeyword('seconds') || ctx.isKeyword('second'))) {
         // 'seconds' 不做本地化：所有 locale 的词表都没有时间单位的本地拼写，
         // zh/de 作者同样只能写英文 seconds，报错里的 'seconds' 正是作者该写的词。
-        error("Timeout must specify time unit 'seconds'");
+        error(Issue.invalidValue(tokenName('timeoutUnit'), tokenLit(ctx.peek()), lit('seconds'), "Timeout must specify time unit 'seconds'"));
     }
     ctx.nextWord();
     expectPeriodEnd(ctx, error);
@@ -724,17 +730,17 @@ function parseCases(ctx, error) {
     ctx.pushCompoundContext(KW.MATCH);
     try {
         if (!ctx.at(TokenKind.INDENT))
-            error('Expected indent for cases');
+            error(Issue.expectedIn(tokenName('indent'), tokenName('matchCases'), 'Expected indent for cases'));
         ctx.next();
         while (!ctx.at(TokenKind.DEDENT)) {
             if (!ctx.isKeyword(KW.WHEN)) {
                 // 改进的错误消息，提示复合模式关系
-                error(`Expected ${kwq(ctx, KW.WHEN, 'When')} (若...为 pattern requires '为' after '若')`);
+                error(Issue.expectedIn(kwParam(KW.WHEN), tokenName('matchCase'), `Expected ${kwq(ctx, KW.WHEN, 'When')} (若...为 pattern requires '为' after '若')`));
             }
             const whenTok = ctx.nextWord();
             const pat = parsePattern(ctx, error);
             if (!ctx.at(TokenKind.COMMA))
-                error("Expected ',' after pattern");
+                error(Issue.expectedAfter(lit(','), tokenName('pattern'), "Expected ',' after pattern"));
             ctx.next();
             const body = parseCaseBody(ctx, error);
             const caseNode = Node.Case(pat, body);
@@ -806,13 +812,13 @@ function parseIfExpr(ctx, error) {
     const cond = parseOr(ctx, error);
     skipInlineThenLayout(ctx);
     if (!ctx.isKeyword(KW.THEN))
-        error(`Expected ${kwq(ctx, KW.THEN)} in if-expression`);
+        error(Issue.expectedIn(kwParam(KW.THEN), tokenName('ifExpression'), `Expected ${kwq(ctx, KW.THEN)} in if-expression`));
     ctx.nextWord(); // 消费 THEN
     const thenE = parseExpr(ctx, error);
     skipInlineElseLayout(ctx);
     if (!ctx.isKeyword(KW.ELSE) && !ctx.isKeyword(KW.OTHERWISE)) {
-        error(`Expected ${kwKindq(ctx, SemanticTokenKind.OTHERWISE, 'else')} in if-expression ` +
-            `(${kwKind(ctx, SemanticTokenKind.OTHERWISE, 'else')} is mandatory for expression-level if)`);
+        error(Issue.expectedIn(kwParam(KW.OTHERWISE), tokenName('ifExpression'), `Expected ${kwKindq(ctx, SemanticTokenKind.OTHERWISE, 'else')} in if-expression ` +
+            `(${kwKind(ctx, SemanticTokenKind.OTHERWISE, 'else')} is mandatory for expression-level if)`));
     }
     ctx.nextWord(); // 消费 ELSE / OTHERWISE
     const elseE = parseExpr(ctx, error);
@@ -1284,7 +1290,7 @@ function parseApplyOrPrimary(ctx, error) {
     if (ctx.isKeyword(KW.APPLY) && applyLooksLikeCall(ctx)) {
         const applyTok = ctx.nextWord();
         const fn = parseCallTargetName(ctx, error);
-        expectKeyword(ctx, error, KW.TO_WORD, `Use '${kw(ctx, KW.APPLY)} <fn> ${kw(ctx, KW.TO_WORD)} <arg>' (expected ${kwq(ctx, KW.TO_WORD)}).`);
+        expectKeyword(ctx, error, KW.TO_WORD, Issue.expectedIn(kwParam(KW.TO_WORD), kwParam(KW.APPLY), `Use '${kw(ctx, KW.APPLY)} <fn> ${kw(ctx, KW.TO_WORD)} <arg>' (expected ${kwq(ctx, KW.TO_WORD)}).`));
         const arg = parseExpr(ctx, error);
         const call = Node.Call(fn, [arg]);
         assignSpan(call, spanFromSources(applyTok, arg));
@@ -1323,7 +1329,7 @@ function applyLooksLikeCall(ctx) {
 function parseCallTargetName(ctx, error) {
     const startTok = ctx.peek();
     if (!ctx.at(TokenKind.IDENT) && !ctx.at(TokenKind.TYPE_IDENT)) {
-        error(`Expected a function name after ${kwq(ctx, KW.APPLY)}.`);
+        error(Issue.expectedAfter(tokenName('functionName'), kwParam(KW.APPLY), `Expected a function name after ${kwq(ctx, KW.APPLY)}.`));
     }
     const consumed = [ctx.peek()];
     let full = ctx.at(TokenKind.IDENT) ? parseIdent(ctx, error) : ctx.next().value;
@@ -1393,7 +1399,7 @@ function operatorWordBeforeParen(ctx, english) {
 function parseOperatorWordCall(ctx, error, word, english) {
     const symbol = english ? null : OPERATOR_WORD_SYMBOLS.get(word);
     if (!symbol) {
-        error(`运算符词 ${kwq(ctx, word)} 不能用作前缀调用；只有符号运算符 ${PREFIX_SYMBOL_LIST} 可以写成 op(a, b)`);
+        error(Issue.invalidValue(tokenName('prefixOperator'), kwParam(word), lit(PREFIX_SYMBOL_LIST), `运算符词 ${kwq(ctx, word)} 不能用作前缀调用；只有符号运算符 ${PREFIX_SYMBOL_LIST} 可以写成 op(a, b)`));
     }
     return parsePrefixOperatorCall(ctx, error, symbol, kwParts(word).length);
 }
@@ -1404,7 +1410,7 @@ function parsePrefixOperatorCall(ctx, error, op, opTokenCount = 1) {
         ctx.next();
     const args = parseArgList(ctx, error);
     if (args.length !== 2)
-        error(`前缀操作符调用需要 2 个参数，但实际为 ${args.length}`);
+        error(Issue.callArity(tokenName('prefixOperatorCall'), 2, args.length, `前缀操作符调用需要 2 个参数，但实际为 ${args.length}`));
     const target = assignTokenSpan(Node.Name(op), opTok);
     return assignSpan(Node.Call(target, args), spanFromTokens(opTok, lastNonLayoutToken(ctx)));
 }
@@ -1425,7 +1431,7 @@ function parsePrimary(ctx, error) {
         const functionTok = ctx.nextWord(); // 'function'
         const params = parseParamList(ctx, error);
         expectCommaOr(ctx);
-        expectKeyword(ctx, error, KW.PRODUCE, `Expected ${kwq(ctx, KW.PRODUCE)} and return type`);
+        expectKeyword(ctx, error, KW.PRODUCE, Issue.expected(kwParam(KW.PRODUCE), `Expected ${kwq(ctx, KW.PRODUCE)} and return type`));
         let retType;
         if (ctx.at(TokenKind.COLON)) {
             retType = Node.TypeName('Unknown');
@@ -1435,7 +1441,7 @@ function parsePrimary(ctx, error) {
             retType = parseType(ctx, error);
         }
         if (!ctx.at(TokenKind.COLON))
-            error("Expected ':' after return type in lambda");
+            error(Issue.expectedAfterIn(lit(':'), tokenName('returnType'), tokenName('lambda'), "Expected ':' after return type in lambda"));
         ctx.next();
         expectNewline(ctx, error);
         const body = parseBlock(ctx, error);
@@ -1591,7 +1597,7 @@ function parsePrimary(ctx, error) {
         const awaitTok = ctx.nextWord();
         const args = parseArgList(ctx, error);
         if (args.length !== 1)
-            error('await(expr) takes exactly one argument');
+            error(Issue.callArity(lit('await'), 1, args.length, 'await(expr) takes exactly one argument'));
         const target = assignTokenSpan(Node.Name('await'), awaitTok);
         const call = Node.Call(target, args);
         const endTok = lastNonLayoutToken(ctx);
@@ -1616,7 +1622,7 @@ function parsePrimary(ctx, error) {
             }
         }
         if (!ctx.at(TokenKind.RBRACKET))
-            error("Expected ']' to close list literal");
+            error(Issue.expectedIn(lit(']'), tokenName('listLiteral'), "Expected ']' to close list literal"));
         const rbrackTok = ctx.next();
         const list = Node.ListLit(elements);
         assignSpan(list, spanFromSources(lbrackTok, rbrackTok));
@@ -1627,7 +1633,7 @@ function parsePrimary(ctx, error) {
         const lparenTok = ctx.next();
         const expr = parseExpr(ctx, error);
         if (!ctx.at(TokenKind.RPAREN))
-            error("Expected ')' after expression");
+            error(Issue.expectedAfter(lit(')'), tokenName('expression'), "Expected ')' after expression"));
         const rparenTok = ctx.next();
         assignSpanFromSources(expr, lparenTok, rparenTok, expr);
         return expr;
@@ -1645,7 +1651,7 @@ function parsePrimary(ctx, error) {
             const withTok = ctx.nextWord();
             const fields = [];
             let hasMore = true;
-            const setToMissing = `Expected '${kw(ctx, KW.SET)} ${kw(ctx, KW.TO_WORD)}' in construction`;
+            const setToMissing = Issue.expectedIn(kwParam(KW.SET), tokenName('construction'), `Expected '${kw(ctx, KW.SET)} ${kw(ctx, KW.TO_WORD)}' in construction`);
             while (hasMore) {
                 const nameTok = ctx.peek();
                 // 字段位置不是名字（如 `helper with 10` 这种 with 调用后缀）：与 Java 引擎
@@ -1659,7 +1665,7 @@ function parsePrimary(ctx, error) {
                 const equalsTok = ctx.peek();
                 ctx.nextWord();
                 if (!ctx.isKeyword(KW.TO_WORD))
-                    error(`Expected ${kwq(ctx, KW.TO_WORD)} after ${kwq(ctx, KW.SET)} in construction`);
+                    error(Issue.expectedAfterIn(kwParam(KW.TO_WORD), kwParam(KW.SET), tokenName('construction'), `Expected ${kwq(ctx, KW.TO_WORD)} after ${kwq(ctx, KW.SET)} in construction`));
                 ctx.nextWord();
                 const e = parseExpr(ctx, error);
                 const fld = {
@@ -1703,7 +1709,7 @@ function parsePrimary(ctx, error) {
                 full += '.' + partTok.value;
             }
             else {
-                error('Expected identifier after dot');
+                error(Issue.expectedAfter(tokenName('identifier'), lit('.'), 'Expected identifier after dot'));
             }
         }
         const target = Node.Name(full);
@@ -1714,8 +1720,8 @@ function parsePrimary(ctx, error) {
             // 直到运行时才抛 Undefined function；在此于编译期就报错并给出正确写法。
             // 仅拦截裸类型名（无点链后缀），点链形态（如 SomeType.method(...)）不受影响。
             if (full === typeName && ctx.declaredRecordTypes.has(typeName)) {
-                error(`Cannot construct '${typeName}' with positional arguments. ` +
-                    `Use named fields instead: '${typeName} ${kw(ctx, KW.WITH)} <field> ${kw(ctx, KW.SET)} ${kw(ctx, KW.TO_WORD)} <value> ${kw(ctx, KW.AND)} ...'`);
+                error(Issue.unexpectedConstruct(tokenName('positionalConstruction'), `Cannot construct '${typeName}' with positional arguments. ` +
+                    `Use named fields instead: '${typeName} ${kw(ctx, KW.WITH)} <field> ${kw(ctx, KW.SET)} ${kw(ctx, KW.TO_WORD)} <value> ${kw(ctx, KW.AND)} ...'`));
             }
             const args = parseArgList(ctx, error);
             const call = Node.Call(target, args);
@@ -1752,8 +1758,8 @@ function parsePrimary(ctx, error) {
         if (ctx.at(TokenKind.LPAREN)) {
             // 同 TYPE_IDENT 分支：拦截对已声明类型的位置式构造（无大小写语言里类型名是 IDENT）。
             if (full === name && ctx.declaredRecordTypes.has(name)) {
-                error(`Cannot construct '${name}' with positional arguments. ` +
-                    `Use named fields instead: '${name} ${kw(ctx, KW.WITH)} <field> ${kw(ctx, KW.SET)} ${kw(ctx, KW.TO_WORD)} <value> ${kw(ctx, KW.AND)} ...'`);
+                error(Issue.unexpectedConstruct(tokenName('positionalConstruction'), `Cannot construct '${name}' with positional arguments. ` +
+                    `Use named fields instead: '${name} ${kw(ctx, KW.WITH)} <field> ${kw(ctx, KW.SET)} ${kw(ctx, KW.TO_WORD)} <value> ${kw(ctx, KW.AND)} ...'`));
             }
             const args = parseArgList(ctx, error);
             const call = Node.Call(target, args);
@@ -1763,7 +1769,7 @@ function parsePrimary(ctx, error) {
         }
         return target;
     }
-    error('Unexpected expression');
+    error(Issue.unexpectedConstruct(tokenName('expression'), 'Unexpected expression'));
 }
 /**
  * 解析参数列表
@@ -1773,7 +1779,7 @@ function parsePrimary(ctx, error) {
  */
 export function parseArgList(ctx, error) {
     if (!ctx.at(TokenKind.LPAREN))
-        error("Expected '('");
+        error(Issue.expected(lit('('), "Expected '('"));
     ctx.next();
     const args = [];
     while (!ctx.at(TokenKind.RPAREN)) {
@@ -1786,7 +1792,7 @@ export function parseArgList(ctx, error) {
             break;
     }
     if (!ctx.at(TokenKind.RPAREN))
-        error("Expected ')'");
+        error(Issue.expected(lit(')'), "Expected ')'"));
     ctx.next();
     return args;
 }
@@ -1832,7 +1838,7 @@ export function parsePattern(ctx, error) {
                     break;
             }
             if (!ctx.at(TokenKind.RPAREN))
-                error("Expected ')' in pattern");
+                error(Issue.expectedIn(lit(')'), tokenName('pattern'), "Expected ')' in pattern"));
             const rparenTok = ctx.next();
             const node = Node.PatternCtor(typeName, names);
             assignSpan(node, spanFromSources(typeTok, lparenTok, rparenTok, ...nameTokens));
@@ -2036,7 +2042,7 @@ function parseIdent(ctx, error) {
     if (recovered !== null)
         return recovered;
     if (!ctx.at(TokenKind.IDENT)) {
-        error('Expected identifier');
+        error(Issue.expected(tokenName('identifier'), 'Expected identifier'));
     }
     return ctx.next().value;
 }
@@ -2047,9 +2053,9 @@ function parseIdent(ctx, error) {
  * @param kw 关键字
  * @param msg 错误消息
  */
-function expectKeyword(ctx, error, kw, msg) {
+function expectKeyword(ctx, error, kw, issue) {
     if (!ctx.isKeyword(kw))
-        error(msg);
+        error(issue);
     ctx.nextWord();
 }
 /**
@@ -2068,7 +2074,7 @@ function expectCommaOr(ctx) {
  */
 function expectNewline(ctx, error) {
     if (!ctx.at(TokenKind.NEWLINE))
-        error('Expected newline');
+        error(Issue.expected(tokenName('newline'), 'Expected newline'));
     ctx.next();
 }
 //# sourceMappingURL=expr-stmt-parser.js.map