@code0-tech/triangulum 0.37.2 → 0.38.1

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.
@@ -274,9 +296,10 @@ 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}.
@@ -293,13 +316,17 @@ export declare const normalizeNodeSchema: (schema: Schema) => Schema;
  */
 export declare const nonNullishType: (type: ts.Type) => ts.Type;
 /**
- * Sets a schema's `suggestions` to the given set, dropping the key entirely when
- * the set is empty or missing. Suggestion-carrying schemas are built with the
- * key always present (an empty array when nothing matched), whereas the rest of
- * the pipeline omits it — so every schema that is spread into a result passes
- * through here instead of relying on the spread.
+ * 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, suggestions: Input["suggestions"] | undefined) => T;
+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
@@ -311,7 +338,7 @@ export declare const withSuggestions: <T extends Schema>(schema: T, suggestions:
  * (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?: Input["suggestions"]) => 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
@@ -338,9 +365,9 @@ export declare const declaredSchema: (schema: Schema, anySuggestions?: Input["su
  * This is what {@link ListInput.declaredItems} carries, and it never depends on the
  * entered value.
  */
-export declare const declaredItemsOf: (functionItems: Schema[] | undefined, anySuggestions?: Input["suggestions"]) => Schema[];
-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;
+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

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[];
+};