@bitspark/horos 0.9.0 → 0.11.1

package/dist/src/diagnose.d.ts

@@ -5,21 +5,53 @@ export type Limit = "recursion_depth";
 export declare function limitValue(l: Limit): number;
 /** The completed/incomplete classification of a checking attempt. */
 export type Verdict = "conforms" | "mismatch" | "not_well_formed" | "exhausted";
+/** The kinds of value path step that select by a 0-based index in canonical order. */
+export type StepKind = "item" | "elem" | "key" | "value";
+/**
+ * One step of a value path: `item` of a bare tuple, `elem` of a list or set, `key` or
+ * `value` of a map entry, or the record `field` with this name.
+ */
+export type Step = {
+    readonly kind: StepKind;
+    readonly index: number;
+} | {
+    readonly kind: "field";
+    readonly name: string;
+};
+/** Why the check failed at a location (ADR 0009). */
+export type Reason = "refused" | "missing-field" | "extra-field" | "no-alternative" | "complement" | "limit" | "not-descriptor" | "unknown-constructor" | "arity" | "argument" | "duplicate-field" | "unbound-ref" | "unguarded-ref";
+/**
+ * Where a check failed: the path into the value, the position of the descriptor at fault
+ * (tuple-item indices from the root descriptor), and the reason. `field` names the record
+ * field for `missing-field` and `extra-field`; `arg` is the item index of the faulty argument
+ * for `argument`, `duplicate-field`, `unbound-ref` and `unguarded-ref`.
+ */
+export interface Location {
+    readonly path: readonly Step[];
+    readonly at: readonly number[];
+    readonly reason: Reason;
+    readonly field?: string;
+    readonly arg?: number;
+}
 /**
  * A checking outcome that distinguishes a completed decision from a reached bound.
  *
  * `exhausted` is INCOMPLETE: a statement about THIS bounded attempt, never a claim that the
- * value does or does not have the form, and never a refutation.
+ * value does or does not have the form, and never a refutation. Every outcome other than
+ * `conforms` names its location.
  */
 export type Diagnosis = {
     readonly verdict: "conforms";
 } | {
     readonly verdict: "mismatch";
+    readonly location: Location;
 } | {
     readonly verdict: "not_well_formed";
+    readonly location: Location;
 } | {
     readonly verdict: "exhausted";
     readonly limit: Limit;
+    readonly location: Location;
 };
 /** Whether this outcome is a completed decision. */
 export declare function isComplete(d: Diagnosis): boolean;
@@ -44,13 +76,14 @@ export declare function checkingProfile(): Profile;
 /**
  * Diagnose `wf(T)`: `conforms` when T is a well-formed descriptor, `not_well_formed` when it is
  * conclusively not, and `exhausted` when the well-formedness traversal itself could not finish
- * — the distinction horos-internal#211 asks for by name.
+ * — the distinction horos-internal#211 asks for by name. A non-conforming outcome names the
+ * descriptor position and, where one argument is at fault, its item index.
  */
 export declare function diagnoseWf(t: Value): Diagnosis;
 /**
  * Diagnose `v : T`. Mirrors `conforms`: the `wf(T)` soundness gate runs first (spec §3 MUST),
  * so a descriptor that is not well-formed yields `not_well_formed` and one whose
  * well-formedness could not be decided yields `exhausted` — neither is reported as a mismatch
- * of the value.
+ * of the value. Each carries the well-formedness location, with an empty value path.
  */
 export declare function diagnose(v: Value, t: Value): Diagnosis;