@qoretechnologies/reqraft 0.10.53 → 0.10.54-pr.115.g9bc96ed

package/src/components/form/expressions/dpqlMockLsp.ts

@@ -1,100 +1,126 @@
 // Copyright 2026 Qore Technologies, s.r.o.
-// A compact mock LSP for ExpressionField Text-mode stories. Registers just
-// enough of the DPQL contract on the shared harness plumbing
-// (`smartEditor/__fixtures__/mockLspServer`) to exercise the parse/serialize
-// boundary glue: `dpql/parse` echoes the typed text into an expression AST,
-// `dpql/serialize` reconstructs a string. (The DpqlEditor's own stories
-// carry the full mock; this is the minimal subset.)
+// The DPQL language server every story talks to unless it brings its own.
+//
+// `.storybook/preview.tsx` starts it before each story, so an expression field,
+// a Preview or an Explain panel finds a server on the endpoint whatever story it
+// sits in — the same way `GLOBAL_STORY_MOCK_DATA` answers the REST requests
+// components make on their own. A story that needs different handlers starts
+// its own server on the URL and replaces this one (see `createMockLspServer`).
+// The answers come from `dpqlMockLanguage`, which follows the real server.
 import {
   createMockLspServer,
+  DEFAULT_LSP_CAPABILITIES,
+  IMockLspServer,
   MOCK_LSP_URL,
+  TMockLspHandler,
 } from '../../smartEditor/__fixtures__/mockLspServer';
+import {
+  IDpqlMockNode,
+  mockParseDpql,
+  mockRenderDpql,
+  mockSerializeDpql,
+  mockTokenizeDpql,
+} from './dpqlMockLanguage';
 
-// Loose AST node shape the serialize/render handlers poke at — the mock
-// doesn't validate structure.
-interface IMockExprNode {
-  exp?: string;
-  args?: IMockExprNode[];
-  value?: IMockExprNode;
-  is_expression?: boolean;
+/**
+ * Every `dpql/parse` the mock answered, in order, for diagnosis.
+ *
+ * The type-analysis stories depend on the front end SENDING `target_type` —
+ * the mock returns analysis only when it is present, exactly as the server
+ * behaves. When one of those stories fails there are two very different
+ * causes, and the rendered DOM cannot tell them apart: the request never
+ * carried a target, or it did and the answer was not rendered. This records
+ * which, and the story reports it in its assertion message so the answer
+ * survives into a CI log.
+ */
+export interface IDpqlMockParseCall {
+  text: string;
+  target?: string;
+  analysed: boolean;
 }
+export const dpqlMockParseCalls: IDpqlMockParseCall[] = [];
 
-/** Start the mock LSP; returns a teardown function. */
-export const startDpqlMockLsp = (): (() => void) => {
-  const lsp = createMockLspServer(MOCK_LSP_URL, {
-    capabilities: {
-      textDocumentSync: { openClose: true, change: 2 },
-      completionProvider: { triggerCharacters: ['@', '$', '.', ':'] },
-    },
-    // Unknown requests get an empty success so nothing hangs.
-    defaultResult: {},
-    handlers: {
-      'textDocument/completion': () => ({ isIncomplete: false, items: [] }),
+/** The template namespaces the server offers after a `$`. */
+const DPQL_MOCK_TEMPLATE_ITEMS = [
+  { label: '$data:', insertText: '$data:', kind: 1, detail: 'template' },
+  { label: '$config:', insertText: '$config:', kind: 1, detail: 'template' },
+  { label: '$static:', insertText: '$static:', kind: 1, detail: 'template' },
+  { label: '$timestamp:', insertText: '$timestamp:', kind: 1, detail: 'template' },
+];
+
+/** The record fields the server offers after an `@`. */
+const DPQL_MOCK_FIELD_ITEMS = [
+  { label: '@name', insertText: '@name', kind: 5, detail: 'string' },
+  { label: '@status', insertText: '@status', kind: 5, detail: 'string' },
+];
+
+const DPQL_MOCK_HANDLERS: Record<string, TMockLspHandler> = {
+  /* Position-aware, as the real server is: `$` opens the template
+     namespaces, `@` the record fields. Answering the same list whatever
+     precedes the cursor would make a story asserting the `$` menu pass
+     for a shell that asked in the wrong context — which is the only thing
+     such a story is there to catch. (`DpqlEditor`'s own stories carry the
+     full catalogue; this is the minimal subset.) */
+  'textDocument/completion': (msg, server) => {
+    const position = msg.params?.position ?? { line: 0, character: 0 };
+    const line = server.textOf(msg.params?.textDocument?.uri).split('\n')[position.line] ?? '';
+    const head = line.slice(0, position.character);
+    const sigil = head.match(/[@$][\w:.{}]*$/)?.[0]?.[0] ?? '';
+    if (sigil === '$') {
+      return { isIncomplete: false, items: DPQL_MOCK_TEMPLATE_ITEMS };
+    }
+    if (sigil === '@') {
+      return { isIncomplete: false, items: DPQL_MOCK_FIELD_ITEMS };
+    }
+    return { isIncomplete: false, items: [] };
+  },
+
+  'textDocument/semanticTokens/full': (msg, server) => ({
+    data: mockTokenizeDpql(server.textOf(msg.params?.textDocument?.uri)),
+  }),
 
-      'textDocument/semanticTokens/full': () => ({ data: [] }),
+  'dpql/setContext': () => ({ fields: {} }),
 
-      'dpql/setContext': () => ({ fields: {} }),
+  'dpql/parse': (msg) => {
+    const text = String(msg.params?.text ?? '');
+    const target = msg.params?.target_type as string | undefined;
+    dpqlMockParseCalls.push({ text: text.trim(), target, analysed: !!target });
+    return mockParseDpql(text, target);
+  },
 
-      // Echo the typed text into an `==` expression so the AST is
-      // deterministic and verifiable.
-      'dpql/parse': (msg) => {
-        const text = (msg.params?.text ?? '').trim();
-        return {
-          success: true,
-          expression: {
-            is_expression: true,
-            value: {
-              exp: '==',
-              args: [
-                { type: 'string', value: text || 'x' },
-                { type: 'string', value: '' },
-              ],
-            },
-          },
-          diagnostics: [],
-        };
-      },
+  'dpql/serialize': (msg) => mockSerializeDpql(msg.params?.expression as IDpqlMockNode),
 
-      'dpql/serialize': (msg) => {
-        const expr = msg.params?.expression as IMockExprNode | undefined;
-        const args = expr?.args ?? expr?.value?.args ?? [];
-        const left = args[0]?.value ?? '';
-        const right = args[1]?.value ?? '';
-        return { dpql: `${left} == ${right}`.trim() };
-      },
+  'dpql/validate': () => ({ diagnostics: [] }),
 
-      'dpql/validate': () => ({ diagnostics: [] }),
+  'dpql/renderExpression': (msg) => mockRenderDpql(msg.params?.expression as IDpqlMockNode),
+};
+
+export interface IStartDpqlMockLspOptions {
+  /** Handlers to use instead of, or beside, the default ones. */
+  handlers?: Record<string, TMockLspHandler>;
+  /** Per-method response delays in ms. */
+  delays?: Record<string, number>;
+}
 
-      // Mirrors the server contract: accepts the bare `{exp, args}` AST
-      // or the `{is_expression, value}` wrapper; returns `{ rendered,
-      // richtext }` where `rendered` is the human-readable form.
-      'dpql/renderExpression': (msg) => {
-        const input = msg.params?.expression as IMockExprNode | undefined;
-        const root = input?.value && !input?.exp ? input.value : input;
-        const renderNode = (node: IMockExprNode): string => {
-          if (!node?.exp) return '';
-          const args = (node.args ?? []).map((arg) =>
-            arg?.is_expression && arg.value?.exp
-              ? `(${renderNode(arg.value)})`
-              : typeof arg?.value === 'string'
-                ? JSON.stringify(arg.value)
-                : String(arg?.value)
-          );
-          return /^[^\w\s]+$/.test(node.exp)
-            ? args.join(` ${node.exp} `)
-            : `${node.exp}(${args.join(', ')})`;
-        };
-        const rendered = renderNode(root);
-        return {
-          rendered,
-          richtext: {
-            type: 'richtext',
-            value: [{ type: 'paragraph', children: [{ text: rendered }] }],
-          },
-        };
-      },
+/** Start the mock DPQL language server; returns the server and a teardown. */
+export const startDpqlMockLspServer = (
+  options: IStartDpqlMockLspOptions = {}
+): { lsp: IMockLspServer; stop: () => void } => {
+  dpqlMockParseCalls.length = 0;
+  const lsp = createMockLspServer(MOCK_LSP_URL, {
+    capabilities: {
+      ...DEFAULT_LSP_CAPABILITIES,
+      textDocumentSync: { openClose: true, change: 2 },
+      completionProvider: { triggerCharacters: ['@', '$', '.', ':'] },
     },
+    // Unknown requests get an empty success so nothing hangs.
+    defaultResult: {},
+    delays: options.delays,
+    handlers: { ...DPQL_MOCK_HANDLERS, ...options.handlers },
   });
-
-  return () => lsp.close();
+  return { lsp, stop: () => lsp.close() };
 };
+
+/** Start the mock DPQL language server; returns a teardown function. */
+export const startDpqlMockLsp = (options?: IStartDpqlMockLspOptions): (() => void) =>
+  startDpqlMockLspServer(options).stop;

package/src/components/form/expressions/mockExpressions.ts

@@ -119,7 +119,8 @@ export const mockExpressions: IExpressionSchema[] = [
     return_type: 'bool',
     ui_return_type: 'bool',
     varargs: false,
-    groups: ['String'],
+    groups: ['Comparison'],
+    render_template: '$arg[0] contains $arg[1]${arg[2] ? (ignore case):}',
     args: stringArgs('Substring', 'contains'),
   },
   {
@@ -133,7 +134,8 @@ export const mockExpressions: IExpressionSchema[] = [
     return_type: 'bool',
     ui_return_type: 'bool',
     varargs: false,
-    groups: ['String'],
+    groups: ['Comparison'],
+    render_template: '$arg[0].startsWith($arg[1], $arg[2])',
     args: stringArgs('Start String', 'starts with'),
   },
   {
@@ -147,7 +149,8 @@ export const mockExpressions: IExpressionSchema[] = [
     return_type: 'bool',
     ui_return_type: 'bool',
     varargs: false,
-    groups: ['String'],
+    groups: ['Comparison'],
+    render_template: '$arg[0].endsWith($arg[1], $arg[2])',
     args: stringArgs('End String', 'ends with'),
   },
   // --- Varargs (int) -------------------------------------------------------
@@ -242,7 +245,8 @@ export const mockExpressions: IExpressionSchema[] = [
     return_type: 'bool',
     ui_return_type: 'bool',
     varargs: false,
-    groups: ['String'],
+    groups: ['Comparison'],
+    render_template: '$arg[0] =~ /$arg[1]/$arg[2]',
     args: [
       { name: 'softstring', display_name: 'String Value', ui_type: 'richtext', required: true },
       { name: 'string', display_name: 'Regular Expression', ui_type: 'string', required: true },

package/src/components/form/expressions/renderExpressionToText.ts

@@ -1,15 +1,77 @@
 // Copyright 2026 Qore Technologies, s.r.o.
-// Client-side expression renderer — the offline approximation of an expression
-// AST. Used as the fallback when the LSP "Explain" path
-// (`DataProvider::renderExpression`) is unreachable, and by read-first
-// summaries that must render synchronously. Pure: no transport/socket import,
-// so it stays out of the LSP/nanoid dependency graph.
+// Client-side expression renderer — an approximation of an expression AST for
+// the read-first row summaries, which must render synchronously. Nothing that
+// can wait uses it: Explain and the Text view's Preview wait for the server's
+// `dpql/renderExpression` (see `useRenderExpression`). Pure: no
+// transport/socket import, so it stays out of the LSP/nanoid dependency graph.
 import { IExpression, IExpressionSchema, IExpressionValue } from './types';
 
 /** A symbol made only of non-word characters renders infix (`a == b`). */
 const isOperatorSymbol = (symbol?: string): boolean =>
   !!symbol && /^[^\w\s]+$/.test(symbol);
 
+/**
+ * Operator precedence, lower binds tighter.
+ *
+ * Mirrors `DpqlOperatorPrecedence` in the Qore DataProvider module, which is
+ * the source of truth — the server renders the same ASTs through
+ * `DataProvider::renderExpression`, and a row summary that parenthesised
+ * differently would make the same expression read two ways depending on
+ * whether it was collapsed or open. (It does not model the catalogue's
+ * `render_template`s, so `contains` still reads as a call here.)
+ */
+const PRECEDENCE: Record<string, number> = {
+  '*': 1,
+  '/': 1,
+  '%': 1,
+  '+': 2,
+  '-': 2,
+  '!': 3,
+  '==': 4,
+  '!=': 4,
+  '<': 4,
+  '<=': 4,
+  '>': 4,
+  '>=': 4,
+  '&&': 5,
+  '||': 6,
+};
+
+/** Anything that is not an operator; nothing binds tighter. */
+const PREC_PRIMARY = 0;
+/** Looser than every operator, so a value rendered in it is never wrapped. */
+const PREC_LOOSEST = 7;
+
+/**
+ * Operators whose grouping cannot change the result.
+ *
+ * `+` is deliberately absent: it concatenates when an operand is a string, so
+ * `1 + (2 + "a")` is `"12a"` where `1 + 2 + "a"` is `"3a"`. Dropping its
+ * parentheses would not be a cosmetic simplification.
+ */
+const ASSOCIATIVE = new Set(['&&', '||']);
+
+const precedenceOf = (exp?: string): number => PRECEDENCE[exp ?? ''] ?? PREC_PRIMARY;
+
+/**
+ * The context an operator's argument is rendered in — the same rule as
+ * `DpqlSerializer::getArgumentContext()`.
+ *
+ * The first argument is where left-associative parsing puts a same-precedence
+ * child back, so it needs no parentheses; a later one does, or `1 - (2 - 3)`
+ * reads as `1 - 2 - 3`, which is a different expression.
+ */
+const argumentContext = (exp: string, argn: number): number => {
+  const prec = precedenceOf(exp);
+  return !argn || ASSOCIATIVE.has(exp) ? prec : prec - 1;
+};
+
+/** An argument reaches this as a bare value or as a `{type, value}` envelope. */
+const readArgValue = (arg: unknown): unknown =>
+  arg !== null && typeof arg === 'object' && 'value' in (arg as object)
+    ? (arg as { value: unknown }).value
+    : arg;
+
 const renderLiteral = (value: unknown): string => {
   if (value === undefined || value === null) return 'null';
   if (typeof value === 'string') return JSON.stringify(value);
@@ -17,31 +79,59 @@ const renderLiteral = (value: unknown): string => {
   return String(value);
 };
 
-/**
- * Recursively render an expression AST to readable text — the client-side
- * approximation, used as the fallback when the LSP is unreachable.
- */
-export const renderExpressionToText = (
+/** Renders `value` and wraps it only if it binds looser than `contextPrec`. */
+const renderInContext = (
   value: IExpressionValue | undefined,
-  expressions: IExpressionSchema[] = []
+  expressions: IExpressionSchema[],
+  contextPrec: number
 ): string => {
   if (!value?.exp) return '';
+  /* A `value` expression IS its literal.
+  
+     It is the wrapper the parser puts around a bare literal — typing `null`,
+     or `42`, into the text editor produces one — and it carries no symbol, so
+     rendering it through the generic paths printed the wrapper instead of the
+     value: `value(42)` with a catalogue that names it, `(42)` with one that
+     supplies its empty symbol. The server renders the literal alone, and a
+     summary that disagrees with the preview beside it is worse than either. */
+  if (value.exp === 'value' && (value.args ?? []).length === 1) {
+    const only = (value.args ?? [])[0] as IExpression;
+    if (!only?.is_expression) {
+      return renderLiteral(readArgValue(only));
+    }
+  }
   const schema = expressions.find((e) => e.name === value.exp);
   const symbol = schema?.symbol ?? value.exp;
-  const args = (value.args ?? []).map((arg: IExpression) =>
+  const args = value.args ?? [];
+  // Logical group (subtype 2) → join with the symbol.
+  const isLogicalGroup = schema?.subtype === 2 || value.exp === '&&' || value.exp === '||';
+  // Binary operator → infix. Everything else renders as a call, whose own
+  // parentheses and commas already delimit its arguments.
+  const isInfix = isLogicalGroup || (args.length === 2 && isOperatorSymbol(symbol));
+
+  const parts = args.map((arg: IExpression, argn: number) =>
     arg?.is_expression && arg.value?.exp
-      ? `(${renderExpressionToText(arg.value, expressions)})`
+      ? renderInContext(
+          arg.value,
+          expressions,
+          isInfix ? argumentContext(value.exp as string, argn) : PREC_LOOSEST
+        )
       : renderLiteral(arg?.value)
   );
 
-  // Logical group (subtype 2) → join with the symbol.
-  if (schema?.subtype === 2 || value.exp === '&&' || value.exp === '||') {
-    return args.join(` ${symbol} `);
-  }
-  // Binary operator → infix.
-  if (args.length === 2 && isOperatorSymbol(symbol)) {
-    return `${args[0]} ${symbol} ${args[1]}`;
+  if (!isInfix) {
+    return `${symbol}(${parts.join(', ')})`;
   }
-  // Otherwise function form.
-  return `${symbol}(${args.join(', ')})`;
+
+  const text = isLogicalGroup ? parts.join(` ${symbol} `) : `${parts[0]} ${symbol} ${parts[1]}`;
+  return precedenceOf(value.exp) > contextPrec ? `(${text})` : text;
 };
+
+/**
+ * Recursively render an expression AST to readable text — the client-side
+ * approximation a read-first row summary shows.
+ */
+export const renderExpressionToText = (
+  value: IExpressionValue | undefined,
+  expressions: IExpressionSchema[] = []
+): string => renderInContext(value, expressions, PREC_LOOSEST);

package/src/components/form/expressions/types.ts

@@ -68,6 +68,13 @@ export interface IExpressionSchema {
   return_type: TQorusType;
   ui_return_type: string;
   symbol: string;
+  /**
+   * How the server's readable rendering (`dpql/renderExpression`) spells this
+   * expression, when not by its symbol: `$arg[n]` is an argument, `$symbol` the
+   * symbol, `$args` all arguments, and `${arg[n] ? set : unset}` reads the
+   * argument or its `default_value` — e.g. `$arg[0].startsWith($arg[1], $arg[2])`.
+   */
+  render_template?: string;
   /** Server type code (operator/function); not a reliable infix discriminator. */
   type: number;
   /** `1` normal, `2` logical group (AND/OR). */