@rsconcept/domain 3.0.2 → 3.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsconcept/domain",
-  "version": "3.0.2",
+  "version": "3.1.1",
   "description": "Shared TypeScript domain for RS language, RSForm, RSModel, RSEngine, OSS, and concept-text helpers.",
   "license": "MIT",
   "author": "IRBorisov",
@@ -154,36 +154,37 @@
     "README.md",
     "LICENSE"
   ],
+  "scripts": {
+    "generate": "lezer-generator src/rslang/parser/rslang.grammar -o src/rslang/parser/parser.ts",
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
+    "lintFix": "eslint . --report-unused-disable-directives --max-warnings 0 --fix",
+    "format": "prettier --write \"src/**/*.ts\" \"*.{ts,js}\"",
+    "format:check": "prettier --check \"src/**/*.ts\" \"*.{ts,js}\"",
+    "prepublishOnly": "pnpm run build"
+  },
   "dependencies": {
     "@lezer/common": "^1.5.2",
     "@lezer/lr": "^1.4.10"
   },
   "devDependencies": {
     "@lezer/generator": "^1.8.0",
-    "@types/node": "^26.1.1",
-    "@typescript-eslint/parser": "^8.63.0",
-    "eslint": "^9.39.5",
-    "eslint-plugin-simple-import-sort": "^13.0.0",
-    "globals": "^17.7.0",
-    "prettier": "^3.9.5",
-    "tsdown": "^0.22.4",
+    "@types/node": "^26.4.0",
+    "@typescript-eslint/parser": "^8.69.0",
+    "eslint": "^10.9.1",
+    "eslint-plugin-simple-import-sort": "^14.0.0",
+    "globals": "^17.11.0",
+    "prettier": "^3.9.6",
+    "tsdown": "^0.22.14",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.63.0",
+    "typescript-eslint": "^8.69.0",
     "unrun": "^0.3.1",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.11"
   },
   "publishConfig": {
     "access": "public"
-  },
-  "scripts": {
-    "generate": "lezer-generator src/rslang/parser/rslang.grammar -o src/rslang/parser/parser.ts",
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
-    "lint": "eslint . --report-unused-disable-directives --max-warnings 0",
-    "lintFix": "eslint . --report-unused-disable-directives --max-warnings 0 --fix",
-    "format": "prettier --write \"src/**/*.ts\" \"*.{ts,js}\"",
-    "format:check": "prettier --check \"src/**/*.ts\" \"*.{ts,js}\""
   }
-}
+}

package/src/index.ts

@@ -81,7 +81,7 @@ export {
 } from './parsing/ast';
 export { type CMSyntaxNode, printTree } from './parsing/lezer-tree';
 export { readErrorAnnotation, readTypeAnnotation } from './rslang/ast-annotations';
-export { RSErrorCode, type RSErrorDescription } from './rslang/error';
+export { type EvalStackFrame, formatEvalCallStack,RSErrorCode, type RSErrorDescription } from './rslang/error';
 export { type CalculatorEvaluateOptions, type CalculatorResult, RSCalculator } from './rslang/eval/calculator';
 export { makeValuePath, TUPLE_ID, type Value, type ValuePath } from './rslang/eval/value';
 export { printValue } from './rslang/eval/value-api';

package/src/library/rsmodel-api.ts

@@ -71,6 +71,11 @@ export function generateRandomValue(
       return tuple(factors);
     }
     case TypeID.collection: {
+      // Empty set is a valid sample only when the element domain itself is generatable.
+      // When the count happens to be 0 we would otherwise skip sampling and miss empty basics.
+      if (!canGenerateRandomValue(type.base, basics, cstByAlias)) {
+        return null;
+      }
       const result: Value[] = [];
       const randomElementsCount = Math.floor(Math.random() * (setElementsCount + 1));
       for (let i = 0; i < randomElementsCount; i++) {
@@ -331,6 +336,28 @@ export function addValueElement(
 
 // ========= Internal functions ==========
 
+function canGenerateRandomValue(
+  type: Typification,
+  basics: Map<number, BasicBinding>,
+  cstByAlias: Map<string, { id: number }>
+): boolean {
+  switch (type.typeID) {
+    case TypeID.integer:
+      return true;
+    case TypeID.basic: {
+      const cst = cstByAlias.get(type.baseID);
+      const binding = cst ? basics.get(cst.id) : undefined;
+      return Object.keys(binding ?? {}).length > 0;
+    }
+    case TypeID.tuple:
+      return type.factors.every(factor => canGenerateRandomValue(factor, basics, cstByAlias));
+    case TypeID.collection:
+      return canGenerateRandomValue(type.base, basics, cstByAlias);
+    case TypeID.anyTypification:
+      return false;
+  }
+}
+
 function countBaseElements(cst: ModelEvalFields, engine: RSEngine): number {
   if (!isBasicConcept(cst.cst_type)) {
     return 0;

package/src/rslang/error.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+
+import { type EvalStackFrame,formatEvalCallStack } from './error';
+
+describe('formatEvalCallStack', () => {
+  it('returns empty string for missing or empty stack', () => {
+    expect(formatEvalCallStack(undefined)).toBe('');
+    expect(formatEvalCallStack([])).toBe('');
+  });
+
+  it('formats callee aliases from outermost call to innermost fault', () => {
+    const stack: EvalStackFrame[] = [
+      { alias: 'F12', from: 10, to: 12 },
+      { alias: 'F5', from: 8, to: 14 }
+    ];
+    expect(formatEvalCallStack(stack)).toBe('F5 → F12');
+  });
+
+  it('formats a single nested call', () => {
+    const stack: EvalStackFrame[] = [{ alias: 'F9', from: 7, to: 8 }];
+    expect(formatEvalCallStack(stack)).toBe('F9');
+  });
+});

package/src/rslang/error.ts

@@ -16,15 +16,57 @@ export interface RSErrorInfo {
   params?: readonly string[];
 }
 
+/**
+ * One frame of an evaluation call chain.
+ *
+ * Spans are relative to the formal definition of {@link alias}.
+ * Frames are ordered innermost-first: fault locus, then each caller outward.
+ * The root expression under evaluation is not a frame — its highlight is
+ * {@link RSErrorDescription.from}/{@link RSErrorDescription.to}; {@link RSErrorDescription.stack}
+ * is absent when the fault is in that root expression.
+ */
+export interface EvalStackFrame {
+  /** Constituent whose formal definition contains this span. */
+  alias: string;
+  /** Half-open span `[from, to)` in that definition. */
+  from: number;
+  to: number;
+}
+
 /** Represents RSLang expression error description. */
 export interface RSErrorDescription extends RSErrorInfo {
   from: number;
   to: number;
+  /**
+   * Evaluation call chain when the fault is inside a called `F#`/`P#` body.
+   * Absent for parse/semantic errors and for evaluation errors in the root expression.
+   */
+  stack?: readonly EvalStackFrame[];
 }
 
 /** Error reporter function type. */
 export type ErrorReporter = (error: RSErrorDescription) => void;
 
+/**
+ * Formats an evaluation call chain for display (`F5 → F12`).
+ *
+ * Uses callee aliases from outermost call to innermost fault container.
+ * Returns an empty string when there is no nested call to show.
+ */
+export function formatEvalCallStack(stack: readonly EvalStackFrame[] | undefined): string {
+  if (!stack || stack.length === 0) {
+    return '';
+  }
+  const aliases: string[] = [];
+  for (let index = stack.length - 1; index >= 0; index--) {
+    const frame = stack[index];
+    if (frame) {
+      aliases.push(frame.alias);
+    }
+  }
+  return aliases.join(' → ');
+}
+
 /** Represents RSLang expression error types. */
 export const RSErrorCode = {
   unknownSyntax: 0x8400, // 33792

package/src/rslang/eval/evaluator.test.ts

@@ -308,11 +308,66 @@ describe('Calculator', () => {
       expect(errors[0]).toMatchObject({
         code: RSErrorCode.iterateInfinity,
         from: callSite!.from,
-        to: callSite!.to
+        to: callSite!.to,
+        stack: [{ alias: 'F9', from: zOffset, to: zOffset + 1 }]
       });
+      expect(errors[0]?.stack).toHaveLength(1);
       expect(readErrorAnnotation(callSite!)).toMatchObject({ code: RSErrorCode.iterateInfinity });
       expect(readErrorAnnotation(innerErrorNode!)).toBeNull();
     });
+
+    it('keeps nested call surface span in the root expression and records the full stack', () => {
+      const innerExpr = '[a∈X1] debool(∅)';
+      const midExpr = '[a∈X1] F8[a]';
+      treeContext.set('F8', buildAST(innerExpr));
+      treeContext.set('F7', buildAST(midExpr));
+      const mainAst = buildAST('F7[X1]');
+      const outerCall = findFirstNode(mainAst, TokenID.NT_FUNC_CALL);
+      expect(outerCall).not.toBeNull();
+
+      const midAst = treeContext.get('F7')!;
+      const midCall = findFirstNode(midAst, TokenID.NT_FUNC_CALL);
+      expect(midCall).not.toBeNull();
+
+      const deboolArgFrom = innerExpr.indexOf('∅');
+      calculator.run(mainAst, error => errors.push(error), true);
+
+      expect(errors).toHaveLength(1);
+      expect(errors[0]).toMatchObject({
+        code: RSErrorCode.calcInvalidDebool,
+        from: outerCall!.from,
+        to: outerCall!.to,
+        stack: [
+          { alias: 'F8', from: deboolArgFrom, to: deboolArgFrom + 1 },
+          { alias: 'F7', from: midCall!.from, to: midCall!.to }
+        ]
+      });
+      expect(errors[0]?.stack).toHaveLength(2);
+      expect(readErrorAnnotation(outerCall!)).toMatchObject({ code: RSErrorCode.calcInvalidDebool });
+    });
+
+    it('distinguishes which call site failed when the same function is used twice', () => {
+      treeContext.set('F8', buildAST('[a∈ℬ(X1)] debool(a)'));
+      const mainAst = buildAST('F8[{1}] ∪ F8[X1]');
+      const callSites: AstNode[] = [];
+      visitAstDFS(mainAst, node => {
+        if (node.typeID === TokenID.NT_FUNC_CALL) {
+          callSites.push(node);
+        }
+      });
+      expect(callSites).toHaveLength(2);
+
+      calculator.run(mainAst, error => errors.push(error));
+
+      expect(errors).toHaveLength(1);
+      expect(errors[0]).toMatchObject({
+        code: RSErrorCode.calcInvalidDebool,
+        from: callSites[1].from,
+        to: callSites[1].to,
+        stack: [{ alias: 'F8' }]
+      });
+      expect(errors[0]?.stack).toHaveLength(1);
+    });
   });
 
   describe('evaluation cache', () => {

package/src/rslang/eval/evaluator.ts

@@ -4,7 +4,7 @@
 
 import { type AstNode, getNodeIndices, getNodeText } from '../../parsing';
 import { annotateError } from '../ast-annotations';
-import { type ErrorReporter, RSErrorCode } from '../error';
+import { type ErrorReporter, type EvalStackFrame, RSErrorCode } from '../error';
 import { labelRSLangNode } from '../labels';
 import { TokenID } from '../parser/token';
 
@@ -95,16 +95,59 @@ export class Evaluator {
     this.iterationCounter = 0;
   }
 
-  private errorNode(node: AstNode): AstNode {
-    if (this.callSiteStack.length > 0) {
-      return this.callSiteStack[this.callSiteStack.length - 1];
+  /**
+   * Surface highlight target in the root expression under evaluation.
+   * Nested call sites live in callee ASTs — only the outermost call is in the root.
+   */
+  private surfaceErrorNode(fault: AstNode): AstNode {
+    return this.callSiteStack[0] ?? fault;
+  }
+
+  /**
+   * Builds innermost-first frames for called `F#`/`P#` bodies only.
+   * The root expression is represented by the surface `from`/`to`, not a stack frame.
+   * Returns `undefined` when the fault is in the root expression (no function call).
+   */
+  private buildEvalStack(fault: AstNode): readonly EvalStackFrame[] | undefined {
+    if (this.callSiteStack.length === 0) {
+      return undefined;
+    }
+    const frames: EvalStackFrame[] = [];
+    const innermostCall = this.callSiteStack[this.callSiteStack.length - 1];
+    if (!innermostCall) {
+      return undefined;
+    }
+    frames.push({
+      alias: getNodeText(innermostCall.children[0]),
+      from: fault.from,
+      to: fault.to
+    });
+    // Call sites at index ≥ 1 live in a callee body; index 0 is the root call site.
+    for (let index = this.callSiteStack.length - 1; index >= 1; index--) {
+      const callSite = this.callSiteStack[index];
+      const outerCall = this.callSiteStack[index - 1];
+      if (!callSite || !outerCall) {
+        continue;
+      }
+      frames.push({
+        alias: getNodeText(outerCall.children[0]),
+        from: callSite.from,
+        to: callSite.to
+      });
     }
-    return node;
+    return frames;
   }
 
   private onError(code: RSErrorCode, node: AstNode, params?: string[]): null {
-    const target = this.errorNode(node);
-    this.reporter?.({ code, from: target.from, to: target.to, params });
+    const target = this.surfaceErrorNode(node);
+    const stack = this.buildEvalStack(node);
+    this.reporter?.({
+      code,
+      from: target.from,
+      to: target.to,
+      ...(params !== undefined ? { params } : {}),
+      ...(stack !== undefined ? { stack } : {})
+    });
     if (this.annotateErrors) {
       annotateError(target, code, params);
     }

package/src/rslang/index.ts

@@ -1,5 +1,5 @@
 export { readErrorAnnotation, readTypeAnnotation } from './ast-annotations';
-export { RSErrorCode, type RSErrorDescription } from './error';
+export { type EvalStackFrame, formatEvalCallStack,RSErrorCode, type RSErrorDescription } from './error';
 export { type CalculatorEvaluateOptions, type CalculatorResult, RSCalculator } from './eval/calculator';
 export { makeValuePath, type Value, type ValuePath } from './eval/value';
 export { printValue } from './eval/value-api';