@rytass/bpm-core-nestjs-module 0.18.1 → 0.20.0

package/src/lib/condition/expression-ast.d.ts

@@ -0,0 +1,176 @@
+import { ExpressionLintIssue, ExpressionUsagePoint } from '@rytass/bpm-core-shared';
+import { FormDefinitionSchema, FormFieldDefinition } from '@rytass/bpm-core-shared/form';
+import type { BPMExpressionFunctionRegistry } from '../expression-function/expression-function.types';
+import { ExpressionDialect } from './expression-dialect';
+/**
+ * A chain of member and index steps from a root: `form.items[0].qty` is
+ * `{ root: 'form', segments: ['items', '0', 'qty'] }`. `segments` stops at the
+ * first step that is not a literal (a computed index or a method call), and
+ * `complete` is then `false`.
+ */
+export interface ExpressionFieldPath {
+    readonly complete: boolean;
+    readonly root: string;
+    readonly segments: readonly string[];
+}
+export interface ExpressionFunctionCall {
+    readonly argumentCount: number;
+    readonly name: string;
+    /** `true` for a method call (`x.contains(y)`), `false` for `f(x)`. */
+    readonly receiver: boolean;
+}
+/**
+ * A method or macro called directly on a path from a root:
+ * `form.items.exists(r, ...)` is `{ name: 'exists', path: form.items }`.
+ */
+export interface ExpressionReceiverPath {
+    readonly name: string;
+    readonly path: ExpressionFieldPath;
+}
+/**
+ * A key that is not a literal: an index (`form[k]`, `form.a[form.b]`) or a map
+ * literal key (`{form.k: 1}`). `root` is the root the indexed chain starts at,
+ * `null` for map keys and chains that start elsewhere.
+ */
+export interface ExpressionComputedKey {
+    readonly kind: 'INDEX' | 'MAP_KEY';
+    readonly root: string | null;
+}
+export interface ExpressionReferences {
+    /** Highest nesting of `all`/`exists`/`exists_one`/`map`/`filter`. */
+    readonly comprehensionDepth: number;
+    readonly computedKeys: readonly ExpressionComputedKey[];
+    readonly dialect: ExpressionDialect;
+    /** Paths read on the right of a `/`. */
+    readonly divisorFieldPaths: readonly ExpressionFieldPath[];
+    readonly fieldPaths: readonly ExpressionFieldPath[];
+    /** Top-level form field keys read through `form` or `formData`. */
+    readonly formFieldKeys: readonly string[];
+    readonly functionCalls: readonly ExpressionFunctionCall[];
+    /** Paths tested by `has(...)` or compared with `null`, `""` or `[]`. */
+    readonly guardedFieldPaths: readonly ExpressionFieldPath[];
+    /** The arguments of `has(...)`. */
+    readonly hasArguments: readonly ExpressionFieldPath[];
+    /**
+     * Parsed nodes. cel-v2 counts AST nodes (the engine refuses more than
+     * 200); cel-legacy counts CST atoms, steps and operators, which is a
+     * different measure and only comparable with itself.
+     */
+    readonly nodeCount: number;
+    /** Paths read inside an operand of `||`. */
+    readonly orOperandFieldPaths: readonly ExpressionFieldPath[];
+    readonly receiverPaths: readonly ExpressionReceiverPath[];
+    /** `__proto__`, `constructor` or `prototype` used as a member, key or map key. */
+    readonly reservedSegments: readonly string[];
+    /** Free identifiers: names the expression reads that nothing in it binds. */
+    readonly roots: readonly string[];
+    /** Roots used as a value themselves, not as the start of a path. */
+    readonly wholeRootReferences: readonly string[];
+}
+/**
+ * What `readExpressionReferences` found. `UNAVAILABLE` is a cel-legacy
+ * expression whose parser returned no CST to walk (the unit tests' `cel-js`
+ * shim does that): per docs/24 §1 the old dialect then keeps its textual lint.
+ */
+export type ExpressionReferencesResult = {
+    readonly references: ExpressionReferences;
+    readonly status: 'OK';
+} | {
+    readonly limitExceeded: boolean;
+    readonly status: 'PARSE_FAILED';
+} | {
+    readonly status: 'UNAVAILABLE';
+};
+export declare const RESERVED_PATH_SEGMENTS: ReadonlySet<string>;
+/** ADR 22 §3.4 / docs/24 §2.7. */
+export declare const EXPRESSION_MAX_COMPREHENSION_DEPTH = 2;
+/** Unique top-level keys of the paths rooted at `form` or `formData`, in first-seen order. */
+export declare const readFormFieldKeys: (paths: readonly ExpressionFieldPath[]) => readonly string[];
+/**
+ * The roots, field paths, function calls and structure an expression uses,
+ * read from its AST without evaluating it. Names a comprehension binds (`x`
+ * in `form.items.exists(x, x.qty > 0)`) are only in scope inside it: the same
+ * name outside it is a root.
+ *
+ * Works for both dialects. cel-v2 reads the engine's AST; cel-legacy walks the
+ * CST of `cel-js` and answers `UNAVAILABLE` when there is none to walk.
+ */
+export declare function readExpressionReferences(expression: string, dialect?: ExpressionDialect): ExpressionReferencesResult;
+/** Whether the expression reads the top-level form field `fieldKey`. */
+export declare const readsFormField: (references: ExpressionReferences, fieldKey: string) => boolean;
+/**
+ * Whether the expression steps inside the table field `tableKey`
+ * (`form.items.qty`, `form.items[0]`, `form.items.exists(r, ...)`), the AST
+ * twin of `referencesTableInternals` (ADR 16 §3.8). The table as a whole
+ * (`size(form.items)`, `form.items.size()`, `form.items == null`) is not.
+ */
+export declare const readsTableInternals: (references: ExpressionReferences, tableKey: string) => boolean;
+/** The slice of the function registry the lint uses (docs/24 §3: P3 implements it). */
+export type ExpressionFunctionAvailability = Pick<BPMExpressionFunctionRegistry, 'assertPublishable' | 'get'>;
+export interface ExpressionLintContext {
+    /** Overrides the use point's roots. Without either, roots are not checked. */
+    readonly allowedRootIdentifiers?: readonly string[];
+    /**
+     * The bound form. With it, field keys are checked against the schema and
+     * the type check knows each field's type; without it every field is `dyn`.
+     */
+    readonly formSchema?: FormDefinitionSchema | null;
+    /**
+     * The registry that answers which functions are available. Absent means
+     * only the nine built-ins exist (`BPM_BUILT_IN_EXPRESSION_FUNCTION_NAMES`);
+     * `ConditionService` fills it with the registry it was given. Host code:
+     * a throw or a malformed answer is isolated and refuses the names asked
+     * about (`EXPR_FUNCTION_NOT_REGISTERED`), never its message.
+     */
+    readonly functionRegistry?: ExpressionFunctionAvailability | null;
+    /** The field a `SET_FORM_FIELD` writes; decides its result type. */
+    readonly targetField?: FormFieldDefinition | null;
+    readonly usagePoint?: ExpressionUsagePoint;
+}
+/**
+ * The CEL types a form field is declared with for the lint's type check
+ * (docs/24-design/p2-p3 §2.2). Only names the engine accepts are produced;
+ * anything else is `dyn`. Never `optional(...)`: the engine cannot convert it.
+ */
+export declare const readExpressionFieldType: (field: FormFieldDefinition) => string;
+/**
+ * The called function names the registry cannot vouch for, in first-seen
+ * order and without duplicates (ADR 22 §5.3; publish and rollback share it).
+ *
+ * Only names {@link isRegistryFunctionName} accepts — `…_vN` and the nine
+ * built-ins — are put to `assertPublishable`; any other name can never be
+ * registered and is always reported. Without a registry only the built-ins
+ * exist.
+ *
+ * The registry is host code and is isolated: an `assertPublishable` that
+ * throws or answers something other than a list of strings makes every name
+ * asked about unavailable. The result only ever holds names the expression
+ * itself called, never a value the registry returned.
+ */
+export declare function readUnavailableExpressionFunctions(names: readonly string[], registry: ExpressionFunctionAvailability | null | undefined): readonly string[];
+/**
+ * The cel-v2 lint of one expression (ADR 22 §3.4, docs/24 §2.2): errors that
+ * refuse a publish and warnings that do not, in that order. The expression is
+ * expected trimmed and within the length limit (`ConditionService` checks
+ * both first).
+ *
+ * `environmentRegistry` is the registry evaluation will run with (the one
+ * `ConditionService` was given): the expression is parsed and type-checked in
+ * its cel-v2 environment, so the built-ins and the host's functions are
+ * type-checked like the engine's own. Absent means the built-ins only. It is
+ * separate from `context.functionRegistry`, which only answers availability
+ * (`assertPublishable`, `get`) and need not be able to build an environment.
+ *
+ * The type check (`env.check()`) runs only when nothing structural is wrong
+ * and every function called is one that environment knows; a call to one it
+ * does not know is covered by `EXPR_FUNCTION_NOT_REGISTERED` instead.
+ */
+export declare function lintCelV2Expression(expression: string, label: string, context?: ExpressionLintContext, environmentRegistry?: BPMExpressionFunctionRegistry | null): readonly ExpressionLintIssue[];
+/**
+ * The global function names an expression calls that cel-v2 does not provide
+ * itself: the built-ins and host functions a rollback must find registered
+ * (docs/24 §1). `null` when the expression cannot be read. Hand the result to
+ * {@link readUnavailableExpressionFunctions}, which applies the same name
+ * rule and registry isolation as the publish lint.
+ */
+export declare function readExpressionHostFunctionNames(expression: string, dialect?: ExpressionDialect): readonly string[] | null;