@hatua/expressions 0.0.0 → 0.1.0

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/messages.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/nodes.d.ts

@@ -0,0 +1,43 @@
+import { CallNode, Expression, HoleNode, IndexNode, LiteralNode, MemberNode, NameNode, ProjectNode, TemplateNode, TextNode, UnaryNode } from './ast.js';
+/** What the parser hands an action: a match, a list of matches, or nothing. */
+type Matched = unknown;
+/** Flatten whatever a match produced into a string. Stands in for Peggy's `$`. */
+export declare function str(...parts: Matched[]): string;
+export declare function templateNode(segs: Matched): TemplateNode;
+export declare function holeNode(at: Matched, expr: Matched): HoleNode;
+export declare function textNode(chars: Matched): TextNode;
+export declare function ternaryNode(cond: Matched, tail: Matched): Expression;
+/**
+ * Fold `head ( op operand )*` left. PEG has no left recursion, so precedence is
+ * an explicit rule cascade and associativity is decided here — which is
+ * precisely why the parse scenarios are separate from the eval ones.
+ */
+export declare function binaryNode(head: Matched, tail: Matched): Expression;
+export declare function unaryNode(at: Matched, op: Matched, operand: Matched): UnaryNode;
+/** Parentheses group; they leave no node behind. */
+export declare function parenNode(expr: Matched): Expression;
+/**
+ * Attach each suffix to what precedes it.
+ *
+ * A suffix is parsed knowing only where its own punctuation is — the `.`, the
+ * `[`, the `(` — but a node's `at` is documented as the offset of its *first*
+ * character, and `a.b` starts at `a`. So the offset is restamped here, once the
+ * object is known, which is the only point at which it can be.
+ *
+ * It matters because `at` is what an editor squiggles and what a runner logs. A
+ * diagnostic about `s9.name` that points at the dot sends the reader to the
+ * middle of the thing that failed.
+ */
+export declare function postfixNode(base: Matched, suffixes: Matched): Expression;
+export declare function memberSuffix(at: Matched, name: Matched): Omit<MemberNode, 'object'>;
+export declare function projectSuffix(at: Matched): Omit<ProjectNode, 'object'>;
+export declare function indexSuffix(at: Matched, index: Matched): Omit<IndexNode, 'object'>;
+export declare function callSuffix(at: Matched, args: Matched): Omit<CallNode, 'object'>;
+export declare function argList(head: Matched, tail: Matched): Matched[];
+export declare function nameNode(at: Matched, name: Matched): NameNode;
+export declare function nullNode(at: Matched): LiteralNode;
+export declare function boolNode(at: Matched, value: Matched): LiteralNode;
+export declare function numberNode(at: Matched, int: Matched, frac: Matched, exp: Matched): LiteralNode;
+export declare function stringNode(at: Matched, chars: Matched): LiteralNode;
+export declare function escapeChar(char: Matched): string;
+export {};

package/dist/parse.d.ts

@@ -0,0 +1,23 @@
+import { Expression, TemplateNode } from './ast.js';
+import { Diagnostic } from './errors.js';
+/** Parse a whole Template. Throws `ExpressionError` carrying EXPR_PARSE_ERROR. */
+export declare function parseTemplate(source: string): TemplateNode;
+/**
+ * Parse one Expression, with no surrounding `{{ }}`.
+ *
+ * Only the conformance corpus and tooling need this; a field value is always a
+ * whole Template. It exists because precedence and associativity bugs live in
+ * the parse rather than the evaluation, and they are invisible to evaluation
+ * scenarios whenever two parsers build different trees that happen to evaluate
+ * alike on the sample data — the most dangerous divergence there is, because it
+ * passes everything until one workflow hits the disagreeing case.
+ */
+export declare function parseExpression(source: string): Expression;
+/** Parse, returning the diagnostic instead of throwing. */
+export declare function tryParseTemplate(source: string): {
+    ok: true;
+    template: TemplateNode;
+} | {
+    ok: false;
+    diagnostics: readonly Diagnostic[];
+};

package/dist/parse.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/reference.d.ts

@@ -0,0 +1,65 @@
+import { Expression, TemplateNode } from './ast.js';
+/**
+ * Whether an expression is exactly a path.
+ *
+ * Indexing with a literal counts: `s2.messages[0].subject` still names one
+ * value and nothing more. A call does not — the moment something is computed,
+ * there is no target to retarget.
+ */
+export declare function isReference(node: Expression): boolean;
+/** The path a Reference names, or null when the expression is not one. */
+export declare function referencePath(node: Expression): string | null;
+/**
+ * The Reference a whole Template holds, when it holds exactly one and nothing
+ * else — which is the case the builder renders as a pill.
+ *
+ * `Hi {{ steps.s2.name }}` is not one: it is text with a hole in it, and the pill
+ * belongs inside the field rather than instead of it.
+ */
+export declare function templateReference(template: TemplateNode): string | null;
+/** The same, from source, for callers that have not parsed anything yet. */
+export declare function sourceReference(template: string): string | null;
+/**
+ * Every Reference inside an expression, outermost first.
+ *
+ * Outermost, because `s2.messages[].subject` is one Reference and not four:
+ * descending into a node that is already one would name its own prefix a second
+ * time.
+ *
+ * Here rather than beside either caller, because both of them ask the same
+ * question of the same grammar — the builder to draw each Reference as a pill,
+ * a rename to find the ones it invalidates — and two walks of an expression
+ * tree are two chances to forget a node kind. A node kind nobody descends into
+ * is a Reference nothing draws and a rename silently skips.
+ */
+export declare function referencesIn(node: Expression): Expression[];
+/**
+ * Rewrite every Reference under one rooted path, and return the Template.
+ *
+ * `renamePath(t, 'var.old', 'var.new')` repairs `{{ var.old }}` and
+ * `{{ text.upper(var.old) + 1 }}` alike: the walk is over Reference nodes, not
+ * over whether the Template *is* one, so a computed hole is rewritten exactly as
+ * a bare path is. A rewrite keyed on `templateReference` would repair only the
+ * simplest holes and silently skip every interesting one.
+ *
+ * **Prefixes end at a segment boundary.** Renaming `var.to` leaves `var.total`
+ * alone: a path matches when it is `from`, or continues with `.` or `[`.
+ *
+ * ## It declines rather than guesses
+ *
+ * ADR-0008 gives this grammar two generators and no AST→text, so nothing here
+ * reconstructs an expression from its tree. The source is copied through and
+ * only stretches checked character for character against the path the tree
+ * reports are swapped — the discipline `expressionChip` follows to draw a pill.
+ *
+ * Where the two disagree — `{{ var . old }}`, which parses and whose node offset
+ * holds something other than `var.old` — that occurrence is returned untouched.
+ * There is no way to know which stretch to replace without writing text the
+ * grammar cannot produce, and a rename that guessed would corrupt a file Hatua
+ * does not own (ADR-0001). A missed occurrence goes stale and is reported, which
+ * is the state every consumer already handles (ADR-0021).
+ *
+ * A Template that does not parse is returned unchanged: a command runs against
+ * documents that do not project, and half-written text is one of them.
+ */
+export declare function renamePath(source: string, from: string, to: string): string;

package/dist/reference.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/resolve.d.ts

@@ -0,0 +1,95 @@
+import { FunctionSpec } from '#generated/builtins.js';
+import { Expression } from './ast.js';
+import { Value, ValueType } from './value.js';
+/**
+ * What a path does when it resolves to nothing.
+ *
+ * It governs path *resolution* only, never operator semantics — which is what
+ * keeps the truth tables single-valued. `null` still cannot be ordered, whether
+ * it came from a missing key or from a key holding null.
+ */
+export type OnMissing = 'error' | 'null';
+/** A named Template plus the type it must produce. */
+export interface Slot {
+    readonly name: string;
+    readonly template: string;
+    readonly expectedType: ValueType;
+}
+/**
+ * The buckets a path can resolve into, one per root.
+ *
+ * Every root is a key here and nothing resolves outside one, which is what
+ * makes `root()` a table rather than a table with a fallback: a name the
+ * evaluator does not recognise is missing, not a step id to go looking for.
+ * ADR-0014 is the reason a step id is never at the root — `steps.run` and
+ * `run.id` are different buckets, so neither can shadow the other and no
+ * resolution order can decide which wins.
+ */
+export interface EvaluationContext {
+    /** Step outputs, keyed by step id, addressed as `steps.<id>.…`. */
+    readonly steps?: Readonly<Record<string, Value>>;
+    /** Trigger payloads, addressed as `triggers.<id>.…`. */
+    readonly triggers?: Readonly<Record<string, Value>>;
+    /**
+     * The values a Block was called with, addressed as `params.<k>`.
+     *
+     * Supplied per invocation rather than per run: a Block called twice is called
+     * with different arguments, and its parameters are the only part of scope
+     * that changes between two calls of the same Block.
+     */
+    readonly params?: Readonly<Record<string, Value>>;
+    /** Workflow variables, addressed as `var.<key>`. */
+    readonly var?: Readonly<Record<string, Value>>;
+    /** The Host's ambient values for this execution, addressed as `run.<key>`. */
+    readonly run?: Readonly<Record<string, Value>>;
+    /** Which Trigger fired. Needed when several are declared. */
+    readonly TRIGGER?: string | null;
+    /**
+     * The clock `dt.now()` reads.
+     *
+     * Never the system clock: an expression that reads the wall clock is
+     * unfixturable, and two steps in one run would disagree about when "now" was.
+     */
+    readonly now?: Date;
+    readonly onMissing?: OnMissing;
+    readonly functions?: FunctionRegistry;
+}
+/** How a function is implemented. Arguments arrive evaluated and checked. */
+export type FunctionImpl = (args: readonly Value[], context: EvaluationContext) => Value;
+/**
+ * A function is its declaration *and* its implementation, together.
+ *
+ * Keeping them paired is what lets arity and argument types be enforced in one
+ * place rather than at the top of thirty-four implementations, and it is why a
+ * Host's functions need no special handling: a Host declaration produces the
+ * same pair.
+ */
+export interface RegisteredFunction {
+    readonly spec: FunctionSpec;
+    readonly impl: FunctionImpl;
+}
+export type FunctionRegistry = ReadonlyMap<string, RegisteredFunction>;
+/**
+ * Resolve one Slot.
+ *
+ * A Template that is exactly one hole keeps the expression's own type — the
+ * number 24, not the string "24". Anything else interpolates, because mixed
+ * text can only be text.
+ */
+export declare function resolve(context: EvaluationContext, slot: Slot): Value;
+/**
+ * Resolve a whole `with:` map in one call.
+ *
+ * It reports every failure together rather than stopping at the first, because
+ * a user fixing one field at a time is a user running the workflow five times
+ * to find five mistakes.
+ */
+export declare function resolveAll(context: EvaluationContext, slots: readonly Slot[]): Record<string, Value>;
+export declare function evaluate(node: Expression, context: EvaluationContext): Value;
+/**
+ * `==` and `!=` are total: every pair of values has an answer, and no value is
+ * ever converted to reach it. Two different types are simply not equal.
+ */
+export declare function equals(left: Value, right: Value): boolean;
+/** Reconstruct the source path, for a diagnostic that has to name what failed. */
+export declare function pathText(node: Expression): string;

package/dist/sexp.d.ts

@@ -0,0 +1,7 @@
+import { Expression, TemplateNode } from './ast.js';
+export interface SexpOptions {
+    /** Append `@offset` to every node. Only the offset scenarios ask for this. */
+    readonly offsets?: boolean;
+}
+export declare function templateToSexp(template: TemplateNode, options?: SexpOptions): string;
+export declare function toSexp(node: Expression, options?: SexpOptions): string;

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+import { ValueType } from './value.js';
+/**
+ * The declared shape of something addressable.
+ *
+ * `members` describes an object's members, or — for a `list` — the fields of
+ * each element, which is exactly what a Component Manifest's `of:` means.
+ */
+export interface TypeNode {
+    readonly type: ValueType;
+    readonly members?: Readonly<Record<string, TypeNode>>;
+}
+/**
+ * One thing an expression may name, and what it yields.
+ *
+ * Scope arrives as an argument rather than being derived here, so this package
+ * depends on `@hatua/schema` and nothing else — `@hatua/model` builds these
+ * from the document and the manifests, and no cycle appears between them.
+ */
+export interface ScopeEntry {
+    /** The token root: `s2`, `triggers.nightly`, `var.digest_to`, `TRIGGER`. */
+    readonly path: string;
+    readonly type: TypeNode;
+}
+/** The outcome of checking an expression's type against a field's. */
+export type TypeVerdict = 'matches' | 'conflicts' | 'unknown';
+/**
+ * Compare a statically-determined type against a declared one.
+ *
+ * The coercion permitted here is exactly the coercion `satisfies` permits at run
+ * time, stated once at the level of types rather than values: any scalar into
+ * `text`, `null` into anything, and otherwise an exact match.
+ */
+export declare function match(actual: ValueType, declared: ValueType): TypeVerdict;
+/** Types that can be ordered with `<`, `<=`, `>`, `>=`. */
+export declare const ORDERED_TYPES: readonly ValueType[];
+/** Whether a statically-known type could be an operand of an ordered comparison. */
+export declare const canOrder: (type: ValueType) => boolean;
+/** The element shape of a list, which the manifest spells as the list's own `of:`. */
+export declare const elementOf: (node: TypeNode) => TypeNode;

package/dist/validate.d.ts

@@ -0,0 +1,32 @@
+import { FunctionSpec } from '#generated/builtins.js';
+import { Expression } from './ast.js';
+import { Diagnostic } from './errors.js';
+import { ScopeEntry } from './types.js';
+import { ValueType } from './value.js';
+/**
+ * Everything design-time checking needs of a function: what it declares.
+ *
+ * Wider than `FunctionRegistry`, which pairs each declaration with the
+ * implementation that runs it. Checking never calls one — it reads the spec for
+ * arity and argument types and nothing else — so requiring the pair would force
+ * a checker to carry every implementation in the bundle to answer a question
+ * none of them is asked. A `FunctionRegistry` satisfies this, so a runner that
+ * already has one passes it unchanged.
+ */
+export type FunctionDeclarations = ReadonlyMap<string, {
+    readonly spec: FunctionSpec;
+}>;
+export interface CheckContext {
+    /** What this step may address. Sibling branches are deliberately absent. */
+    readonly scope: readonly ScopeEntry[];
+    /** Hatua's functions merged with the Host's. */
+    readonly functions: FunctionDeclarations;
+}
+/**
+ * Check one Template against the type its field declares.
+ *
+ * Returns everything it found. Callers decide what to do with it: the Inspector
+ * renders all of them, Publish looks only at the errors.
+ */
+export declare function validate(template: string, expectedType: ValueType, context: CheckContext): Diagnostic[];
+export declare function inferType(node: Expression, context: CheckContext, found: Diagnostic[]): ValueType;

package/dist/value.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The value space.
+ *
+ * Two rules make everything else in this package tractable, and both are
+ * pinned by ADR-0009:
+ *
+ *   - There is exactly one absent value, `null`. A missing key yields it, and
+ *     reading a property of it yields it again. Nothing here ever produces
+ *     `undefined`.
+ *   - There is one numeric type and it is a 64-bit float, so `7 / 2` is 3.5 in
+ *     both languages. Go must never reach for `int`.
+ *
+ * `NaN` and `Infinity` are not in the space at all: division by zero is an
+ * error rather than a value, which is what keeps them out.
+ */
+/**
+ * Every type a value or a declaration can name.
+ *
+ * The first seven are the Component Manifest's own output types, so a field's
+ * declared type and an expression's type are drawn from one vocabulary rather
+ * than two that have to be mapped. `unknown` and `null` exist only here.
+ */
+export type ValueType = 'text' | 'number' | 'boolean' | 'datetime' | 'list' | 'object' | 'item' | 'unknown' | 'null';
+export type Value = string | number | boolean | Date | readonly Value[] | {
+    readonly [key: string]: Value;
+} | null;
+/** The runtime type of a value, in the same vocabulary a manifest declares. */
+export declare function typeOf(value: Value): ValueType;
+/**
+ * Whether a value satisfies a declared type.
+ *
+ * Coercion at the boundary is narrow and declared, so "must match" has a
+ * precise meaning:
+ *
+ *   - any scalar into `text` is permitted — a `text` field is the universal
+ *     sink, and that is exactly what interpolation already does;
+ *   - `text` into `number` is *not* implicit; it requires `num.parse()`;
+ *   - `null` satisfies any declared type. Whether absence is *acceptable* is
+ *     `req:`'s business, not the evaluator's;
+ *   - everything else must match exactly.
+ */
+export declare function satisfies(value: Value, declared: ValueType): boolean;
+export declare function isScalar(type: ValueType): boolean;
+/**
+ * Render a value as text at a `text` boundary.
+ *
+ * Numbers go through the ECMAScript `Number::toString` algorithm, which Go does
+ * not implement — `String(1e-6)` is `"0.000001"` in JavaScript and `"1e-06"` in
+ * Go. TypeScript gets it for free; the Go side ports it. A workflow that emails
+ * a number must not read differently depending on which runner sent it.
+ */
+export declare function asText(value: Value): string;
+/**
+ * RFC 3339 in UTC, with a fractional part only when there is one.
+ *
+ * `Date.toISOString()` always writes three decimal places and Go's RFC3339Nano
+ * writes none for a whole second, so neither language's default would do. This
+ * spelling is Go's, and TypeScript is the one that has to be told.
+ *
+ * Instants carry millisecond precision, which is what `Date` can hold; the Go
+ * side truncates to match rather than quietly keeping nanoseconds one runner
+ * would print and the other could not.
+ */
+export declare function datetimeToText(value: Date): string;
+/**
+ * Canonical JSON — what `json.stringify` produces.
+ *
+ * Hand-rolled in both languages rather than reaching for the built-in, because
+ * the two built-ins disagree in ways that would reach a user: Go sorts object
+ * keys and JavaScript preserves insertion order, Go escapes `<` and `&` by
+ * default, and each formats numbers its own way. Sorting keys in both is the
+ * only choice that can be made identical, so both sort.
+ */
+export declare function toJson(value: Value): string;
+/**
+ * Compare two strings by code point.
+ *
+ * JavaScript's `<` compares UTF-16 code units, and Go's compares UTF-8 bytes.
+ * Those agree for everything in the basic multilingual plane and disagree above
+ * it: a surrogate pair sorts *before* U+E000..U+FFFF in JavaScript and *after*
+ * them in Go, so `list.sort(['fi', '😀'])` came out in opposite orders. Go's byte
+ * order is already code point order, so this is what TypeScript has to be told.
+ *
+ * It matters most for `json.stringify`, whose keys are sorted precisely so the
+ * two languages produce one string.
+ */
+export declare function compareText(left: string, right: string): number;
+/**
+ * Half away from zero, which is Go's `math.Round`.
+ *
+ * `Math.round` rounds halves toward *positive infinity*, so it disagrees on
+ * every negative half. Reflecting the negative case and letting `Math.round` do
+ * the work is the whole fix; reimplementing rounding is how
+ * `sign * floor(abs + 0.5)` got written, which is wrong just below a half.
+ *
+ * Anything that rounds must come through here. `num.round` and `dt.add` both
+ * did their own thing, and only one of them was right.
+ */
+export declare function roundHalfAwayFromZero(value: number): number;
+/** ECMAScript `Number::toString`. Named so the Go port has something to point at. */
+export declare function numberToText(value: number): string;

package/package.json

@@ -1,17 +1,41 @@
 {
   "name": "@hatua/expressions",
-  "version": "0.0.0",
-  "description": "Placeholder reserving the name. Nothing is published here; see 0.1.0 and later.",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Internal to @hatua/react — published because it is an external of its build, not a supported API. The {{ … }} expression language: parse, check, resolve.",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/pedromvgomes/hatua.git",
     "directory": "source/packages/expressions"
   },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "imports": {
+    "#generated/*": "./src/generated/*",
+    "#nodes": "./src/nodes.ts"
+  },
   "publishConfig": {
     "access": "public"
   },
-  "files": [
-    "README.md"
-  ]
+  "dependencies": {
+    "@hatua/schema": "0.1.0"
+  },
+  "devDependencies": {
+    "yaml": "^2.8.1"
+  },
+  "scripts": {
+    "build": "vite build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text-summary --coverage.reporter=json-summary --coverage.reporter=lcovonly"
+  }
 }

package/README.md

@@ -1,5 +0,0 @@
-# @hatua/expressions
-
-This version reserves the package name and contains no code.
-
-Install `0.1.0` or later.