@code0-tech/triangulum 0.37.1 → 0.38.0

package/dist/util/schema.util.d.ts

@@ -1,5 +1,7 @@
 import { default as ts, FunctionDeclaration } from 'typescript';
-import { FunctionDefinition, LiteralValue, NodeFunction, ReferenceValue, SubFlowValue } from '@code0-tech/sagittarius-graphql-types';
+import { FunctionDefinition } from '@code0-tech/sagittarius-graphql-types';
+import { SuggestionCandidate, SuggestionCertainty, SuggestionValue } from './suggestion.util';
+export type { SuggestionCandidate, SuggestionCertainty, SuggestionMatch, SuggestionMatchReason, SuggestionValue, } from './suggestion.util';
 /**
  * Maps a data type identifier to a dedicated input kind.
  *
@@ -50,7 +52,27 @@ export interface Input {
      */
     type?: string;
     /** Array of suggested values (functions, references, or literals) */
-    suggestions?: (NodeFunction | ReferenceValue | LiteralValue | SubFlowValue)[];
+    suggestions?: SuggestionValue[];
+    /**
+     * How certainly each entry of `suggestions` produces this slot's type,
+     * index-aligned with it and of the same length — `suggestions[i]` is
+     * described by `suggestionCertainty[i]`.
+     *
+     * A suggestion is `exact` when its own type is assignable to the slot's, and
+     * `possible` when the match was only reached by weakening one of the two
+     * sides: a generic return matched through its constraint, an `any` that fits
+     * everything, a union whose branches do not all fit, a value that may be
+     * nullish where the slot is not (see {@link SuggestionCertainty}).
+     *
+     * Both kinds are listed — a `possible` candidate is often the one the user
+     * wants — but the split answers two questions the flat list cannot: whether a
+     * slot has *dedicated* producers (which a consumer may want to offer ahead of
+     * building a value by hand), and whether picking one is the case that may
+     * need a cast to type-check.
+     *
+     * Present exactly when `suggestions` is.
+     */
+    suggestionCertainty?: SuggestionCertainty[];
 }
 /**
  * Represents a generic input type with no specific structure.
@@ -189,8 +211,42 @@ export interface DataInput extends Input {
  */
 export interface ListInput extends Input {
     input?: "list";
-    /** Schema or array of schemas for list items */
+    /**
+     * Schema or array of schemas for list items.
+     *
+     * In a parameter schema this is *value-driven*: once an array value is
+     * entered it holds exactly one entry per entered element, so it says what the
+     * list currently contains — not what an element may be. Use
+     * {@link ListInput.declaredItems} for the latter.
+     *
+     * An entered entry only ever *refines* one of the `declaredItems`: it is that
+     * option's input kind, properties and suggestions, with the concrete value's
+     * `type` and per-element cardinality filled in. A union element type is
+     * resolved to the member the entered element picked, so the COLOR entries of a
+     * `LIST<COLOR | OBJECT<…>>` stay color inputs and its object entries keep the
+     * declared object's property schemas.
+     */
     items?: Schema[];
+    /**
+     * The item schemas the *declared* element type produces — what `items` holds
+     * while no value is entered, and therefore the answer to "what may an element
+     * of this list be": its input kind, and the suggestions an element slot offers.
+     * A union element contributes one entry per member (e.g. all six methods of a
+     * `LIST<HTTP_METHOD>`), so the entries enumerate the element's options rather
+     * than the list's contents.
+     *
+     * Always present alongside `items` on an input slot's schema — an entered
+     * value can empty `items` (`[]`) or reduce it to the elements that happen to be
+     * there, and neither tells the UI what to render for a new element or which
+     * candidates the element slot accepts. An unconstrained element slot (a generic
+     * `LIST<T>`, or a list in a slot the declared type does not describe) yields a
+     * single generic entry carrying the "accepts anything" suggestion set.
+     *
+     * Omitted on schemas that describe a *produced* value rather than an input slot
+     * (a signature's return type, {@link getTypeSchema}); there `items` is already
+     * the declared expansion.
+     */
+    declaredItems?: Schema[];
 }
 /**
  * Represents a type input.
@@ -240,14 +296,49 @@ export declare const getSchema: (checker: ts.TypeChecker, node: ts.VariableDecla
  *   concrete value must never surface one; the resolved element types (via
  *   `items`) are kept, and the `list-file` `mimetype` is dropped because a plain
  *   list has no such field.
- * - Drops an empty `suggestions` array. Node schemas are built with suggestions
- *   enabled and therefore always carry the key — even when empty — whereas the
- *   rest of the pipeline omits it entirely when there are none.
+ * - Drops an empty `suggestions` array (and its `suggestionCertainty` twin). Node
+ *   schemas are built with suggestions enabled and therefore always carry the
+ *   keys — even when empty — whereas the rest of the pipeline omits them
+ *   entirely when there are none.
  *
  * The function-side schema still drives the final input kind in
  * {@link mergeSchemas}.
  */
 export declare const normalizeNodeSchema: (schema: Schema) => Schema;
+/**
+ * Strips `undefined` and `null` from a union type so the *declared* shape can be
+ * inspected. An optional parameter (or property) resolves to
+ * `<declared> | undefined`, and a union carries none of its members' type flags —
+ * so a test like "is this an object" or `checker.isArrayType` answers `false` for
+ * every optional slot unless the nullish part is removed first. A union that has
+ * more than one real member left is returned unchanged: there is no single
+ * declared shape to speak of then.
+ */
+export declare const nonNullishType: (type: ts.Type) => ts.Type;
+/**
+ * Sets a schema's suggestions to the given candidates, dropping both the
+ * `suggestions` key and its `suggestionCertainty` twin entirely when the set is
+ * empty or missing. Suggestion-carrying schemas are built with the keys always
+ * present (empty arrays when nothing matched), whereas the rest of the pipeline
+ * omits them — so every schema that is spread into a result passes through here
+ * instead of relying on the spread.
+ *
+ * Taking candidates rather than two parallel arrays is what keeps the pair
+ * aligned: there is no call site that can set one without the other.
+ */
+export declare const withSuggestions: <T extends Schema>(schema: T, candidates: SuggestionCandidate[] | undefined) => T;
+/**
+ * A declared (function-side) schema kept as the answer for its position, because
+ * the node side has no counterpart to merge into it — e.g. a property the entered
+ * value does not carry, or a union-typed position whose members no longer line up.
+ *
+ * The declared schema already carries the suggestions of every level it
+ * describes; only a fully generic slot inside it is rewritten to the constant
+ * `any` set, which is what the merge itself would have produced for such a slot
+ * (see {@link genericNodeSchema}). Empty suggestion arrays are dropped so the
+ * result follows the same convention as every other schema.
+ */
+export declare const declaredSchema: (schema: Schema, anySuggestions?: SuggestionCandidate[] | undefined) => Schema;
 /**
  * Treats a node-side schema as sitting in a fully generic ("accepts anything")
  * slot: the declared type constrains nothing here, so the value keeps its shape
@@ -264,8 +355,37 @@ export declare const normalizeNodeSchema: (schema: Schema) => Schema;
  * type-parameter constraint — e.g. `keyof T` — so they are kept). Descendants are
  * always overridden regardless.
  */
-export declare const genericNodeSchema: (schema: Schema, anySuggestions?: Input["suggestions"], overrideRoot?: boolean) => Schema;
-export declare const mergeSchemas: (functionSchema: Schema | undefined, nodeSchema: Schema, valueProvided?: boolean, anySuggestions?: Input["suggestions"], topLevel?: boolean) => Schema;
+/**
+ * The declared element expansion of a list slot: the function-side `items`, each
+ * kept as the declared answer for its position (see {@link declaredSchema}). An
+ * element the declared type leaves unconstrained — a generic `LIST<T>`, or a list
+ * in a slot with no declared type at all — yields a single generic entry carrying
+ * the "accepts anything" set, which is what such an element slot accepts.
+ *
+ * This is what {@link ListInput.declaredItems} carries, and it never depends on the
+ * entered value.
+ */
+export declare const declaredItemsOf: (functionItems: Schema[] | undefined, anySuggestions?: SuggestionCandidate[] | undefined) => Schema[];
+export declare const genericNodeSchema: (schema: Schema, anySuggestions?: SuggestionCandidate[] | undefined, overrideRoot?: boolean) => Schema;
+export declare const mergeSchemas: (functionSchema: Schema | undefined, nodeSchema: Schema, valueProvided?: boolean, anySuggestions?: SuggestionCandidate[] | undefined, topLevel?: boolean) => Schema;
+/**
+ * Checks whether a union's members are the *options of one input* rather than
+ * alternative inputs: a string/number literal union (`'GET' | 'POST' | …`, which
+ * renders as a single select offering all of them) or `boolean` (internally the
+ * union `true | false`, which renders as a single boolean input).
+ *
+ * The distinction decides whether an entered value may narrow a union-typed slot
+ * to the single member it picked. For an options union it must not: narrowing
+ * `HTTP_METHOD` to the entered "GET" would hide the five other options of the
+ * very select the user is filling. For a union of alternative inputs
+ * (`COLOR | OBJECT<…>`, `TEXT | NUMBER`) it must: the member the value picked is
+ * the one input of the set that describes it, and it is also the entry the slot's
+ * {@link ListInput.declaredItems} already offers for it.
+ *
+ * @param type - The type to check
+ * @returns True if the type is a union whose members are options of one input
+ */
+export declare function isOptionsUnion(type: ts.Type): boolean;
 /**
  * Checks if a type is a callable type (has call signatures).
  *

package/dist/util/subflows.util.d.ts

@@ -1,5 +1,6 @@
 import { default as ts } from 'typescript';
-import { FunctionDefinition, SubFlowValue } from '@code0-tech/sagittarius-graphql-types';
+import { FunctionDefinition } from '@code0-tech/sagittarius-graphql-types';
+import { SuggestionCandidate } from './suggestion.util';
 /**
  * Extracts and creates a list of SubFlowValue objects from function declarations
  * that are compatible with the given parameter type.
@@ -13,7 +14,8 @@ import { FunctionDefinition, SubFlowValue } from '@code0-tech/sagittarius-graphq
  * @param {FunctionDefinition[]} functions - Array of function definitions for reference lookup
  * @param {ts.Type} paramType - The target parameter type that functions must be compatible with
  *
- * @returns {SubFlowValue[]} An array of SubFlowValue objects for compatible functions,
- *          or an empty array if the paramType is not a sub-flow type
+ * @returns {SuggestionCandidate[]} An array of sub-flow candidates for compatible
+ *          functions, each carrying how certainly it satisfies the slot, or an
+ *          empty array if the paramType is not a sub-flow type
  */
-export declare const getSubFlows: (checker: ts.TypeChecker, functionDeclarations: ts.FunctionDeclaration[], functions: FunctionDefinition[], paramType: ts.Type) => SubFlowValue[];
+export declare const getSubFlows: (checker: ts.TypeChecker, functionDeclarations: ts.FunctionDeclaration[], functions: FunctionDefinition[], paramType: ts.Type) => SuggestionCandidate[];

package/dist/util/suggestion.util.d.ts

@@ -0,0 +1,161 @@
+import { default as ts } from 'typescript';
+import { LiteralValue, NodeFunction, ReferenceValue, SubFlowValue } from '@code0-tech/sagittarius-graphql-types';
+/**
+ * A value a slot can be filled with: a literal option of the slot's own type, a
+ * reference to something already in scope, a function node whose result is fed
+ * into the slot, or a function bound as a sub-flow.
+ */
+export type SuggestionValue = NodeFunction | ReferenceValue | LiteralValue | SubFlowValue;
+/**
+ * How certain it is that a suggestion actually produces the slot's type.
+ *
+ * - `exact`: the candidate's own type is assignable to the slot's type. Picking
+ *   it always yields a value the slot accepts.
+ * - `possible`: the match was only reached by weakening one of the two sides —
+ *   the candidate *can* produce a fitting value, but is not guaranteed to. See
+ *   {@link SuggestionMatchReason} for what was weakened.
+ *
+ * Both kinds are offered: a `possible` candidate is frequently the one the user
+ * wants (a generic `std::object::get`, a reference into an optional field). The
+ * distinction exists so a consumer can tell "this slot has dedicated producers"
+ * from "everything happens to fit here", and because a `possible` pick is the
+ * case that may need a cast to type-check.
+ */
+export type SuggestionMatch = "exact" | "possible";
+/**
+ * Why a suggestion matched only possibly.
+ *
+ * - `unconstrained`: one of the two sides constrains nothing (`any`, `unknown`,
+ *   `{}`) — the candidate fits every slot, or the slot is fit by every candidate.
+ *   Either way the match says nothing about this pairing.
+ * - `generic`: the candidate's type is a type parameter and the match was made
+ *   against its constraint. A concrete instantiation may be narrower.
+ * - `union-member`: the candidate is a union and only some of its members fit.
+ *   Which member materializes is a runtime decision.
+ * - `nullable`: the candidate may be `null`/`undefined` where the slot is not.
+ *
+ * Listed weakest first: a candidate weakened on several axes reports the first
+ * of these that applies (see {@link weakestCertainty}).
+ */
+export type SuggestionMatchReason = "unconstrained" | "generic" | "union-member" | "nullable";
+/**
+ * The certainty of a single suggestion. `reason` is present exactly when
+ * `match` is `possible`.
+ */
+export interface SuggestionCertainty {
+    match: SuggestionMatch;
+    reason?: SuggestionMatchReason;
+}
+/**
+ * A suggestion together with its certainty — the form suggestions travel in
+ * while a schema is being built.
+ *
+ * On the finished schema the two halves are split into the index-aligned
+ * `suggestions` / `suggestionCertainty` pair (see {@link Input}) so the
+ * suggestion values stay plain GraphQL values a consumer can use as-is. Every
+ * step in between passes candidates around instead of the two arrays, so the
+ * alignment cannot drift.
+ */
+export interface SuggestionCandidate {
+    value: SuggestionValue;
+    certainty: SuggestionCertainty;
+}
+/** The certainty of a candidate that is guaranteed to fit its slot. */
+export declare const EXACT_MATCH: SuggestionCertainty;
+/** The certainty of a candidate that fits only under the given condition. */
+export declare const possibleMatch: (reason: SuggestionMatchReason) => SuggestionCertainty;
+/** Pairs each value with {@link EXACT_MATCH}, for sources that cannot be weakened. */
+export declare const exactCandidates: (values: SuggestionValue[]) => SuggestionCandidate[];
+/**
+ * Picks the stronger of two certainties for the same value — `exact` wins, and
+ * among two `possible` ones the first is kept. Used when the same suggestion is
+ * collected twice against differently scoped types (see the merge in
+ * getSignatureSchema): the slot accepts it for the better of the two reasons.
+ */
+export declare const strongerCertainty: (a: SuggestionCertainty, b: SuggestionCertainty) => SuggestionCertainty;
+/**
+ * Picks the weakest of the given certainties: a candidate weakened on more than
+ * one axis (e.g. a generic return that also turns out to be `any`) is only as
+ * strong as its weakest link. `exact` is the result only when nothing was
+ * weakened at all.
+ */
+export declare const weakestCertainty: (...certainties: SuggestionCertainty[]) => SuggestionCertainty;
+/**
+ * True for a type that constrains nothing, so an assignability test against it
+ * is vacuous: `any` and `unknown`, the empty object type — `{}`, which every
+ * non-nullish value satisfies and which is what a generic `OBJECT<T>` or an
+ * uninstantiated payload bound resolves to — and an object whose only structure
+ * is an index signature that says nothing about its values either. That last
+ * case is what an `OBJECT<T>` instantiated without an argument resolves to:
+ * `{[key: string]: any}`, a slot every object fits. A signature with a real
+ * value type (`Record<string, NUMBER>`) does constrain, and keeps its slot
+ * concrete.
+ *
+ * It matters on both sides of a match. A candidate of this type fits every slot,
+ * and a *slot* of this type is fitted by every candidate — the second case is
+ * the one that would otherwise report a hundred exact "producers" for a slot
+ * that simply accepts anything.
+ *
+ * A callable, an array and anything with properties is excluded: those
+ * constrain their values. An index signature is inspected only `depth` levels
+ * deep (one, from the outside) because an index type may refer back to its own
+ * container (`type Json = {[key: string]: Json}`).
+ */
+export declare const isUnconstrainedType: (type: ts.Type | undefined, depth?: number) => boolean;
+/**
+ * Decides whether a candidate type fits an expected (slot) type, and how
+ * certainly — the shared rule behind every assignability-based suggestion
+ * source.
+ *
+ * Returns `null` when the candidate does not fit at all. Otherwise the match is
+ * `exact`, or `possible` with the reason the fit is not guaranteed:
+ *
+ * - either side constrains nothing (`any`, `unknown`, `{}`) → `unconstrained`.
+ *   For the candidate that means it fits everywhere; for the slot that it is
+ *   fitted by everything. Neither tells the consumer that this candidate is a
+ *   producer *of this type*, which is the whole point of the distinction. This
+ *   only *weakens* the verdict — whether the candidate fits at all is still
+ *   decided by assignability, so an open candidate is not waved through into a
+ *   slot that would reject it;
+ * - the candidate is a union and only some members fit → `union-member`. A
+ *   union is only assignable as a whole when *every* member is, so the partial
+ *   case is exactly the one strict assignability would reject while the slot can
+ *   still be served at runtime;
+ * - the candidate may be nullish where the slot is not → `nullable`. The nullish
+ *   part is deliberately ignored for matching (a `string | null` producer is a
+ *   useful suggestion for a `string` slot), which is what makes the distinction
+ *   worth reporting.
+ *
+ * A purely nullish candidate strips down to `never`, which is assignable to
+ * anything, and is therefore rejected explicitly.
+ */
+export declare const typeMatchCertainty: (type: ts.Type, checker: ts.TypeChecker, expectedType: ts.Type) => SuggestionCertainty | null;
+/**
+ * Reads a schema's suggestions back as candidates. A schema that carries
+ * suggestions without certainties (produced before the pair existed, or hand
+ * written) is read as fully exact rather than rejected.
+ */
+export declare const suggestionCandidates: (schema: {
+    suggestions?: SuggestionValue[];
+    suggestionCertainty?: SuggestionCertainty[];
+}) => SuggestionCandidate[];
+/**
+ * Splits candidates into the schema's index-aligned pair of keys, both keys
+ * always present — the convention of a freshly collected schema, which carries
+ * the keys even when nothing matched (an empty array marks "this is an input
+ * slot and these are all its candidates", which normalizeNodeSchema then
+ * collapses). Use {@link suggestionFields} everywhere else.
+ */
+export declare const suggestionPair: (candidates: SuggestionCandidate[]) => {
+    suggestions: SuggestionValue[];
+    suggestionCertainty: SuggestionCertainty[];
+};
+/**
+ * Splits candidates back into the schema's index-aligned pair of keys. Both keys
+ * are omitted for an empty set, matching the convention that a schema without
+ * suggestions carries neither key.
+ */
+export declare const suggestionFields: (candidates: SuggestionCandidate[] | undefined) => {
+    suggestions?: SuggestionValue[];
+    suggestionCertainty?: SuggestionCertainty[];
+};