@hatua/expressions 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pedro Gomes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/ast.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The AST.
+ *
+ * Every node carries `at`, the offset of its first character in the Template.
+ * That is what lets a diagnostic point at the failing sub-expression rather
+ * than at the whole field, and it is why the grammar's one per-language rule
+ * exists at all — reading the current offset is the single construct pigeon and
+ * Peggy spell differently.
+ */
+export interface TemplateNode {
+    readonly kind: 'Template';
+    readonly segments: readonly Segment[];
+}
+export type Segment = TextNode | HoleNode;
+/** Literal text between holes. */
+export interface TextNode {
+    readonly kind: 'Text';
+    readonly value: string;
+}
+/** One `{{ … }}`. */
+export interface HoleNode {
+    readonly kind: 'Hole';
+    readonly at: number;
+    readonly expr: Expression;
+}
+export type Expression = NameNode | MemberNode | IndexNode | ProjectNode | CallNode | UnaryNode | BinaryNode | TernaryNode | LiteralNode;
+/** A bare identifier: the root of a path, or a function's namespace. */
+export interface NameNode {
+    readonly kind: 'Name';
+    readonly at: number;
+    readonly name: string;
+}
+export interface MemberNode {
+    readonly kind: 'Member';
+    readonly at: number;
+    readonly object: Expression;
+    readonly name: string;
+}
+export interface IndexNode {
+    readonly kind: 'Index';
+    readonly at: number;
+    readonly object: Expression;
+    readonly index: Expression;
+}
+/** `a[]` — "that field of every element". */
+export interface ProjectNode {
+    readonly kind: 'Project';
+    readonly at: number;
+    readonly object: Expression;
+}
+/**
+ * A call. `object` is whatever the `(` was applied to, which is a Member for
+ * every well-formed call — `dt.now()` is Call(Member(Name(dt), now)). Keeping
+ * it structural rather than special-casing `namespace.name` is what lets
+ * `f(a)(b)` and `json.parse(x)['k']` compose without extra grammar.
+ */
+export interface CallNode {
+    readonly kind: 'Call';
+    readonly at: number;
+    readonly object: Expression;
+    readonly args: readonly Expression[];
+}
+export type UnaryOperator = '!' | '-';
+export interface UnaryNode {
+    readonly kind: 'Unary';
+    readonly at: number;
+    readonly op: UnaryOperator;
+    readonly operand: Expression;
+}
+export type BinaryOperator = '??' | '||' | '&&' | '==' | '!=' | '<' | '<=' | '>' | '>=' | '+' | '-' | '*' | '/' | '%';
+export interface BinaryNode {
+    readonly kind: 'Binary';
+    readonly at: number;
+    readonly op: BinaryOperator;
+    readonly left: Expression;
+    readonly right: Expression;
+}
+export interface TernaryNode {
+    readonly kind: 'Ternary';
+    readonly at: number;
+    readonly cond: Expression;
+    /**
+     * Named `whenTrue`/`whenFalse` rather than `then`/`otherwise`: an object with
+     * a `then` property is a thenable, and an AST node that changes behaviour
+     * when it happens to be awaited is a trap nobody would find twice.
+     */
+    readonly whenTrue: Expression;
+    readonly whenFalse: Expression;
+}
+export type LiteralType = 'text' | 'number' | 'boolean' | 'null';
+export interface LiteralNode {
+    readonly kind: 'Literal';
+    readonly at: number;
+    readonly type: LiteralType;
+    readonly value: string | number | boolean | null;
+}
+/** Every node that carries an offset. */
+export type Located = HoleNode | Expression;
+export declare const isExpression: (node: Segment | Expression) => node is Expression;

package/dist/ast.test.d.ts

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

package/dist/conformance.test.d.ts

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

package/dist/errors.d.ts

@@ -0,0 +1,39 @@
+import { DiagnosticCode, Severity } from '#generated/diagnostics.js';
+export type { DiagnosticCode, Phase, Severity } from '#generated/diagnostics.js';
+export { DIAGNOSTICS } from '#generated/diagnostics.js';
+export interface Diagnostic {
+    readonly code: DiagnosticCode;
+    /** Errors block Publish; warnings inform and block nothing. */
+    readonly severity: Severity;
+    /** Offset of the failing construct within the Template. */
+    readonly at: number;
+    /** The Slot this Template was being resolved into, when there is one. */
+    readonly slot?: string;
+    readonly message: string;
+}
+/**
+ * Fill a `{name}` template.
+ *
+ * Two lines rather than a formatting library because the Go half has to produce
+ * byte-identical output: a message that reads one way in the builder and
+ * another in a runner's logs is a support ticket nobody can close.
+ */
+export declare function formatMessage(template: string, args?: Readonly<Record<string, string>>): string;
+export declare function diagnostic(code: DiagnosticCode, at: number, args?: Readonly<Record<string, string>>, slot?: string): Diagnostic;
+/**
+ * Thrown by `resolve` and `resolveAll`.
+ *
+ * It carries a list, not a single failure: `resolveAll` does a whole `with:`
+ * map in one call and 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 class ExpressionError extends Error {
+    readonly diagnostics: readonly Diagnostic[];
+    constructor(diagnostics: readonly Diagnostic[]);
+    /** The first failure's code — the common case is exactly one. */
+    get code(): DiagnosticCode | undefined;
+}
+export declare const errorsIn: (diagnostics: readonly Diagnostic[]) => readonly Diagnostic[];
+/** Whether a set of diagnostics blocks Publish. Warnings never do. */
+export declare const blocksPublish: (diagnostics: readonly Diagnostic[]) => boolean;

package/dist/functions/dt.d.ts

@@ -0,0 +1,2 @@
+import { FunctionImpl } from '../resolve.js';
+export declare const dtFunctions: Record<string, FunctionImpl>;

package/dist/functions/json.d.ts

@@ -0,0 +1,2 @@
+import { FunctionImpl } from '../resolve.js';
+export declare const jsonFunctions: Record<string, FunctionImpl>;

package/dist/functions/list.d.ts

@@ -0,0 +1,2 @@
+import { FunctionImpl } from '../resolve.js';
+export declare const listFunctions: Record<string, FunctionImpl>;

package/dist/functions/num.d.ts

@@ -0,0 +1,2 @@
+import { FunctionImpl } from '../resolve.js';
+export declare const numFunctions: Record<string, FunctionImpl>;

package/dist/functions/registry.d.ts

@@ -0,0 +1,29 @@
+import { FunctionSpec } from '#generated/builtins.js';
+import { ExpressionError } from '../errors.js';
+import { FunctionImpl, FunctionRegistry } from '../resolve.js';
+import { Value } from '../value.js';
+/** A well-typed argument that is nonetheless unusable. */
+export declare function badArgument(name: string, param: string, actual: string): ExpressionError;
+/**
+ * Hatua's own functions, checked against the declaration.
+ *
+ * The check is the point of decision 9: each language supplies implementations
+ * only, and verifies its registry against the shared YAML at load time. A
+ * function implemented here and not declared — or declared and not implemented
+ * — is a divergence between the two runtimes waiting to happen, and it fails
+ * here rather than at the call site in production.
+ */
+export declare function coreFunctions(): FunctionRegistry;
+/**
+ * Merge a Host's functions into Hatua's.
+ *
+ * A collision is a loud error rather than a silent winner. Either answer —
+ * Hatua wins, or the Host wins — is a workflow that behaves differently
+ * depending on which registry was built first, and neither is discoverable from
+ * the workflow.
+ */
+export declare function mergeRegistries(...registries: readonly FunctionRegistry[]): FunctionRegistry;
+/** Build a registry from Host-declared signatures and their implementations. */
+export declare function hostFunctions(specs: readonly FunctionSpec[], implementations: Readonly<Record<string, FunctionImpl>>): FunctionRegistry;
+/** Everything a function implementation is allowed to assume about its list arguments. */
+export declare const asList: (value: Value) => readonly Value[];

package/dist/functions/registry.test.d.ts

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

package/dist/functions/text.d.ts

@@ -0,0 +1,2 @@
+import { FunctionImpl } from '../resolve.js';
+export declare const textFunctions: Record<string, FunctionImpl>;

package/dist/generated/builtins.d.ts

@@ -0,0 +1,33 @@
+import { ValueType } from '../value.js';
+export interface ParamSpec {
+    readonly name: string;
+    readonly type: ValueType;
+    /** One sentence saying what this parameter is for. */
+    readonly description: string;
+    readonly optional: boolean;
+    readonly variadic: boolean;
+}
+export interface NamespaceSpec {
+    readonly namespace: string;
+    /** One sentence describing the group, shown above its functions. */
+    readonly summary: string;
+}
+/**
+ * The namespaces, for a picker that groups functions before listing them.
+ * Declarations only — reading this pulls in no implementation.
+ */
+export declare const CORE_NAMESPACES: readonly NamespaceSpec[];
+export interface FunctionSpec {
+    readonly namespace: string;
+    readonly name: string;
+    /** `namespace.name` — how an expression addresses it. */
+    readonly qualified: string;
+    readonly summary: string;
+    readonly params: readonly ParamSpec[];
+    readonly returns: ValueType;
+}
+/**
+ * What every implementation is checked against at load time. Neither
+ * language may add, rename or re-sign a function on its own.
+ */
+export declare const CORE_FUNCTIONS: readonly FunctionSpec[];

package/dist/generated/diagnostics.d.ts

@@ -0,0 +1,17 @@
+/** Errors block Publish. Warnings inform and block nothing. */
+export type Severity = 'error' | 'warning';
+/** `check` is design time; `eval` is run time. */
+export type Phase = 'check' | 'eval';
+export type DiagnosticCode = 'EXPR_PARSE_ERROR' | 'EXPR_UNKNOWN_REFERENCE' | 'EXPR_UNKNOWN_FUNCTION' | 'EXPR_ARITY_MISMATCH' | 'EXPR_ARGUMENT_TYPE' | 'EXPR_TYPE_MISMATCH' | 'EXPR_TYPE_UNKNOWN' | 'EXPR_OPERAND_TYPE' | 'EXPR_FUNCTION_COLLISION' | 'EVAL_MISSING_PATH' | 'EVAL_TYPE_MISMATCH' | 'EVAL_OPERAND_TYPE' | 'EVAL_COMPARE_NULL' | 'EVAL_COMPARE_TYPES' | 'EVAL_NUMERIC_OVERFLOW' | 'EVAL_DIVISION_BY_ZERO' | 'EVAL_UNKNOWN_FUNCTION' | 'EVAL_ARITY_MISMATCH' | 'EVAL_BAD_ARGUMENT';
+export interface DiagnosticSpec {
+    readonly code: DiagnosticCode;
+    readonly severity: Severity;
+    readonly phase: Phase;
+    /** Template. `{name}` holes are filled by `formatMessage`. */
+    readonly message: string;
+}
+/**
+ * Severity is part of the shared contract. A code that errors here and
+ * warns in Go would let a workflow publish from one builder and not another.
+ */
+export declare const DIAGNOSTICS: Record<DiagnosticCode, DiagnosticSpec>;

package/dist/generated/parser.d.ts

@@ -0,0 +1,209 @@
+/** Provides information pointing to a location within a source. */
+export interface Location {
+  /** Line in the parsed source (1-based). */
+  readonly line: number
+  /** Column in the parsed source (1-based). */
+  readonly column: number
+  /** Offset in the parsed source (0-based). */
+  readonly offset: number
+}
+
+/**
+ * Anything that can successfully be converted to a string with `String()`
+ * so that it can be used in error messages.
+ *
+ * The GrammarLocation class in Peggy is a good example.
+ */
+export interface GrammarSourceObject {
+  readonly toString: () => string
+
+  /**
+   * If specified, allows the grammar source to be embedded in a larger file
+   * at some offset.
+   */
+  readonly offset?: undefined | ((loc: Location) => Location)
+}
+
+/**
+ * Most often, you just use a string with the file name.
+ */
+export type GrammarSource = string | GrammarSourceObject
+
+/** The `start` and `end` position's of an object within the source. */
+export interface LocationRange {
+  /**
+   * A string or object that was supplied to the `parse()` call as the
+   * `grammarSource` option.
+   */
+  readonly source: GrammarSource
+  /** Position at the beginning of the expression. */
+  readonly start: Location
+  /** Position after the end of the expression. */
+  readonly end: Location
+}
+
+/**
+ * Expected a literal string, like `"foo"i`.
+ */
+export interface LiteralExpectation {
+  readonly type: 'literal'
+  readonly text: string
+  readonly ignoreCase: boolean
+}
+
+/**
+ * Range of characters, like `a-z`
+ */
+export type ClassRange = [start: string, end: string]
+
+export interface ClassParts extends Array<string | ClassRange> {}
+
+/**
+ * Expected a class, such as `[^acd-gz]i`
+ */
+export interface ClassExpectation {
+  readonly type: 'class'
+  readonly parts: ClassParts
+  readonly inverted: boolean
+  readonly ignoreCase: boolean
+}
+
+/**
+ * Expected any character, with `.`
+ */
+export interface AnyExpectation {
+  readonly type: 'any'
+}
+
+/**
+ * Expected the end of input.
+ */
+export interface EndExpectation {
+  readonly type: 'end'
+}
+
+/**
+ * Expected some other input.  These are specified with a rule's
+ * "human-readable name", or with the `expected(message, location)`
+ * function.
+ */
+export interface OtherExpectation {
+  readonly type: 'other'
+  readonly description: string
+}
+
+export type Expectation =
+  | AnyExpectation
+  | ClassExpectation
+  | EndExpectation
+  | LiteralExpectation
+  | OtherExpectation
+
+/**
+ * Pass an array of these into `SyntaxError.prototype.format()`
+ */
+export interface SourceText {
+  /**
+   * Identifier of an input that was used as a grammarSource in parse().
+   */
+  readonly source: GrammarSource
+  /** Source text of the input. */
+  readonly text: string
+}
+
+export declare class SyntaxError extends globalThis.SyntaxError {
+  /**
+   * Constructs the human-readable message from the machine representation.
+   *
+   * @param expected Array of expected items, generated by the parser
+   * @param found Any text that will appear as found in the input instead of
+   *   expected
+   */
+  static buildMessage(expected: Expectation[], found?: string | null | undefined): string
+  readonly expected: Expectation[]
+  readonly found: string | null | undefined
+  readonly location: LocationRange
+  readonly name: string
+  constructor(
+    message: string,
+    expected: Expectation[],
+    found: string | null,
+    location: LocationRange,
+  )
+
+  /**
+   * With good sources, generates a feature-rich error message pointing to the
+   * error in the input.
+   * @param sources List of {source, text} objects that map to the input.
+   */
+  format(sources: SourceText[]): string
+}
+
+/**
+ * Trace execution of the parser.
+ */
+export interface ParserTracer {
+  trace: (event: ParserTracerEvent) => void
+}
+
+export type ParserTracerEvent =
+  | {
+      readonly type: 'rule.enter'
+      readonly rule: string
+      readonly location: LocationRange
+    }
+  | {
+      readonly type: 'rule.fail'
+      readonly rule: string
+      readonly location: LocationRange
+    }
+  | {
+      readonly type: 'rule.match'
+      readonly rule: string
+      readonly location: LocationRange
+      /** Return value from the rule. */
+      readonly result: unknown
+    }
+
+export type StartRuleNames = 'Template' | 'ExpressionEntry'
+export interface ParseOptions<T extends StartRuleNames = 'Template'> {
+  /**
+   * String or object that will be attached to the each `LocationRange` object
+   * created by the parser. For example, this can be path to the parsed file
+   * or even the File object.
+   */
+  readonly grammarSource?: GrammarSource
+  readonly startRule?: T
+  readonly tracer?: ParserTracer
+
+  // Internal use only:
+  readonly peg$library?: boolean
+  // Internal use only:
+  peg$currPos?: number
+  // Internal use only:
+  peg$silentFails?: number
+  // Internal use only:
+  peg$maxFailExpected?: Expectation[]
+  // Extra application-specific properties
+  [key: string]: unknown
+}
+
+export declare const StartRules: StartRuleNames[]
+export declare const parse: typeof ParseFunction
+
+// Overload of ParseFunction for each allowedStartRule
+
+declare function ParseFunction<Options extends ParseOptions<'Template'>>(
+  input: string,
+  options?: Options,
+): any
+
+declare function ParseFunction<Options extends ParseOptions<'ExpressionEntry'>>(
+  input: string,
+  options?: Options,
+): any
+
+declare function ParseFunction<Options extends ParseOptions<StartRuleNames>>(
+  input: string,
+  options?: Options,
+): any

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { CORE_FUNCTIONS, CORE_NAMESPACES, type FunctionSpec, type NamespaceSpec, type ParamSpec, } from '#generated/builtins.js';
+export type * from './ast.js';
+export * from './errors.js';
+export { coreFunctions, hostFunctions, mergeRegistries, } from './functions/registry.js';
+export * from './parse.js';
+export * from './reference.js';
+export * from './resolve.js';
+export { templateToSexp, toSexp } from './sexp.js';
+export * from './types.js';
+export * from './validate.js';
+export * from './value.js';