@suss/resolution 0.10.0 → 0.12.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as _suss_datalog from '@suss/datalog';
-import { Database } from '@suss/datalog';
+import { Database, Atom, Tuple, Proof } from '@suss/datalog';
 
 /** The tuples of one relation, as strings, which is all a case compares. */
 type FactsOf = (relation: string) => string[][];
@@ -36,6 +36,75 @@ declare function checkFactContract(sources: Readonly<Record<string, CaseFiles>>,
     problem: string;
 }[]>;
 
+/**
+ * Turn a witness proof over the resolution rules into the chain a
+ * person reads: which value led to which, one reason per hop, with the
+ * assumptions the chain rests on called out.
+ *
+ * This module knows which rules are hops and which are plumbing: a
+ * `stepsTo` firing is a hop somebody should see, a `reaches` firing is
+ * the closure gluing hops together, and the base cases ("x is already
+ * a function") end a chain without adding to it. Everything here is
+ * about the resolution rules; the engine stays prose-free. Atoms in a
+ * proof are the adapter's node ids, so every sentence goes through a
+ * caller-supplied `describe` to say them in source terms.
+ */
+
+/** How a caller says an atom in source terms: a name, a file, a line. */
+type DescribeAtom = (atom: Atom) => string;
+/** One hop of a chain, with the sentence saying why it is true. */
+interface ResolutionStep {
+    from: Atom;
+    to: Atom;
+    /** The rule that fired, by the name it was given. */
+    rule: string;
+    /** Why this hop is true, in one sentence. */
+    reason: string;
+    /** Detail under the hop: barrel re-exports, a callee's own chain. */
+    notes: string[];
+    /** What the hop rests on beyond what the source says. */
+    assumptions: string[];
+}
+interface ResolutionExplanation {
+    /** The chain's atoms in order, the asked-about value first. */
+    atoms: Atom[];
+    steps: ResolutionStep[];
+    /** All assumptions from every step, in chain order. */
+    assumptions: string[];
+    /** True when the depth cap or the cycle guard stopped the walk. */
+    truncated: boolean;
+}
+/** What a phrase reads: the fired rule's premises, spoken through `describe`. */
+interface StepContext {
+    tuple: Tuple;
+    premises: readonly Proof[];
+    describe: DescribeAtom;
+    /** Render a nested proof's own hops, for a callee with a chain of its own. */
+    inline: (proof: Proof) => string[];
+}
+type StepPhrase = (context: StepContext) => {
+    reason: string;
+    notes?: string[];
+    assumptions?: string[];
+};
+interface ExplainOptions {
+    describe: DescribeAtom;
+    /** Phrases for a caller's own step rules, over the built-in ones. */
+    phrases?: Record<string, StepPhrase>;
+}
+/**
+ * Flatten a proof of one resolution answer into its chain. Returns
+ * null for a proof that is not over these rules: an absence (the fact
+ * was never derived), or some other rule set's relation.
+ */
+declare function explainResolutionProof(proof: Proof, options: ExplainOptions): ResolutionExplanation | null;
+/**
+ * The explanation as lines a report prints: the chain first, then one
+ * reason per hop with its notes indented under it, then what the chain
+ * assumes. A truncated walk says so instead of trailing off.
+ */
+declare function renderExplanation(explanation: ResolutionExplanation, describe: DescribeAtom): string[];
+
 /** A step to the value x is written as. */
 declare const VALUE_STEP: _suss_datalog.Term;
 /** A step to what running the call x is handed back. */
@@ -76,4 +145,4 @@ declare const RESOLUTION_QUESTIONS: _suss_datalog.Rule[];
 /** The relations `RESOLUTION_QUESTIONS` answers into. */
 declare const ANSWER_RELATIONS: string[];
 
-export { ANSWER_RELATIONS, type CaseFiles, type ContractCase, type ContractOptions, FACT_CONTRACT_CASES, type FactsOf, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, VALUE_STEP, checkFactContract };
+export { ANSWER_RELATIONS, type CaseFiles, type ContractCase, type ContractOptions, type DescribeAtom, type ExplainOptions, FACT_CONTRACT_CASES, type FactsOf, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ResolutionExplanation, type ResolutionStep, type StepContext, type StepPhrase, VALUE_STEP, checkFactContract, explainResolutionProof, renderExplanation };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _suss_datalog from '@suss/datalog';
-import { Database } from '@suss/datalog';
+import { Database, Atom, Tuple, Proof } from '@suss/datalog';
 
 /** The tuples of one relation, as strings, which is all a case compares. */
 type FactsOf = (relation: string) => string[][];
@@ -36,6 +36,75 @@ declare function checkFactContract(sources: Readonly<Record<string, CaseFiles>>,
     problem: string;
 }[]>;
 
+/**
+ * Turn a witness proof over the resolution rules into the chain a
+ * person reads: which value led to which, one reason per hop, with the
+ * assumptions the chain rests on called out.
+ *
+ * This module knows which rules are hops and which are plumbing: a
+ * `stepsTo` firing is a hop somebody should see, a `reaches` firing is
+ * the closure gluing hops together, and the base cases ("x is already
+ * a function") end a chain without adding to it. Everything here is
+ * about the resolution rules; the engine stays prose-free. Atoms in a
+ * proof are the adapter's node ids, so every sentence goes through a
+ * caller-supplied `describe` to say them in source terms.
+ */
+
+/** How a caller says an atom in source terms: a name, a file, a line. */
+type DescribeAtom = (atom: Atom) => string;
+/** One hop of a chain, with the sentence saying why it is true. */
+interface ResolutionStep {
+    from: Atom;
+    to: Atom;
+    /** The rule that fired, by the name it was given. */
+    rule: string;
+    /** Why this hop is true, in one sentence. */
+    reason: string;
+    /** Detail under the hop: barrel re-exports, a callee's own chain. */
+    notes: string[];
+    /** What the hop rests on beyond what the source says. */
+    assumptions: string[];
+}
+interface ResolutionExplanation {
+    /** The chain's atoms in order, the asked-about value first. */
+    atoms: Atom[];
+    steps: ResolutionStep[];
+    /** All assumptions from every step, in chain order. */
+    assumptions: string[];
+    /** True when the depth cap or the cycle guard stopped the walk. */
+    truncated: boolean;
+}
+/** What a phrase reads: the fired rule's premises, spoken through `describe`. */
+interface StepContext {
+    tuple: Tuple;
+    premises: readonly Proof[];
+    describe: DescribeAtom;
+    /** Render a nested proof's own hops, for a callee with a chain of its own. */
+    inline: (proof: Proof) => string[];
+}
+type StepPhrase = (context: StepContext) => {
+    reason: string;
+    notes?: string[];
+    assumptions?: string[];
+};
+interface ExplainOptions {
+    describe: DescribeAtom;
+    /** Phrases for a caller's own step rules, over the built-in ones. */
+    phrases?: Record<string, StepPhrase>;
+}
+/**
+ * Flatten a proof of one resolution answer into its chain. Returns
+ * null for a proof that is not over these rules: an absence (the fact
+ * was never derived), or some other rule set's relation.
+ */
+declare function explainResolutionProof(proof: Proof, options: ExplainOptions): ResolutionExplanation | null;
+/**
+ * The explanation as lines a report prints: the chain first, then one
+ * reason per hop with its notes indented under it, then what the chain
+ * assumes. A truncated walk says so instead of trailing off.
+ */
+declare function renderExplanation(explanation: ResolutionExplanation, describe: DescribeAtom): string[];
+
 /** A step to the value x is written as. */
 declare const VALUE_STEP: _suss_datalog.Term;
 /** A step to what running the call x is handed back. */
@@ -76,4 +145,4 @@ declare const RESOLUTION_QUESTIONS: _suss_datalog.Rule[];
 /** The relations `RESOLUTION_QUESTIONS` answers into. */
 declare const ANSWER_RELATIONS: string[];
 
-export { ANSWER_RELATIONS, type CaseFiles, type ContractCase, type ContractOptions, FACT_CONTRACT_CASES, type FactsOf, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, VALUE_STEP, checkFactContract };
+export { ANSWER_RELATIONS, type CaseFiles, type ContractCase, type ContractOptions, type DescribeAtom, type ExplainOptions, FACT_CONTRACT_CASES, type FactsOf, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ResolutionExplanation, type ResolutionStep, type StepContext, type StepPhrase, VALUE_STEP, checkFactContract, explainResolutionProof, renderExplanation };

package/dist/index.js

@@ -113,6 +113,27 @@ var FACT_CONTRACT_CASES = [
       return facts("callArg").length > 0 ? null : "a construction passes its argument nowhere, so the parameter it lands in has no value";
     }
   },
+  {
+    name: "a name declared as a fallback",
+    requires: "a module-level name declared as a fallback between a property read and a call, `cached || build()` say",
+    // The fallback expression states its branches; each branch has to be
+    // keyed as the value node itself, or the chain stops at the fallback
+    // instead of continuing into whichever branch resolves.
+    check: (facts) => {
+      const branches = facts("fallbackBranch");
+      if (branches.length < 2) {
+        return `expected a fallback with two branches, found ${branches.length}`;
+      }
+      if (distinct(branches.map((row) => row[0] ?? "")) !== 1) {
+        return "the two branches are keyed under different expressions, so nothing says they are alternatives for one value";
+      }
+      const call = facts("call")[0]?.[0];
+      if (call === void 0) {
+        return "the call branch is not written down as a call, so the branch that resolves has nothing behind it";
+      }
+      return branches.some((row) => row[1] === call) ? null : "no branch is the call node itself, so the chain cannot continue into the branch that resolves";
+    }
+  },
   {
     name: "a value another file declares",
     requires: "two files, one declaring a value and the other reading it by name",
@@ -170,6 +191,242 @@ function checkFactContract(sources, emit, options = {}) {
   }, Promise.resolve([]));
 }
 
+// src/explain.ts
+import { ruleLabel } from "@suss/datalog";
+function exportTrail(proof, describe) {
+  if (proof.kind !== "derived") {
+    return [];
+  }
+  const name = ruleLabel(proof.rule);
+  if (name === "re-export") {
+    const [m, n, m2, n2] = proof.premises[0].tuple;
+    return [
+      `${describe(m)} takes ${String(n)} from ${describe(m2)}, where it is called ${String(n2)}`,
+      ...exportTrail(proof.premises[1], describe)
+    ];
+  }
+  if (name === "re-export all") {
+    const [m, m2] = proof.premises[0].tuple;
+    return [
+      `${describe(m)} forwards everything ${describe(m2)} exports`,
+      ...exportTrail(proof.premises[1], describe)
+    ];
+  }
+  return [];
+}
+function argumentReason(proof, describe) {
+  const [, p, a] = proof.tuple;
+  if (proof.kind !== "derived") {
+    return `${describe(p)} is a parameter, and a call passes it ${describe(a)}`;
+  }
+  const f = proof.premises[0].tuple[0];
+  return `${describe(p)} is a parameter of ${describe(f)}, and a call passes it ${describe(a)}`;
+}
+var DEFAULT_PHRASES = {
+  alias: ({ tuple, describe }) => ({
+    reason: `${describe(tuple[0])} is declared as ${describe(tuple[1])}`
+  }),
+  "last write": ({ tuple, describe }) => ({
+    reason: `${describe(tuple[0])} is written more than once, and the last write leaves it as ${describe(tuple[1])}`
+  }),
+  fallback: ({ tuple, describe }) => ({
+    reason: `${describe(tuple[0])} is a fallback expression, and ${describe(tuple[1])} is the branch that resolves`
+  }),
+  import: ({ tuple, premises, describe }) => {
+    const [, module, name] = premises[0].tuple;
+    return {
+      reason: `${describe(tuple[0])} is imported from ${describe(module)} under the name ${String(name)}`,
+      notes: exportTrail(premises[1], describe)
+    };
+  },
+  argument: ({ premises, describe }) => ({
+    reason: argumentReason(premises[0], describe)
+  }),
+  "property read": ({ tuple, premises, describe }) => {
+    const [, object, name] = premises[0].tuple;
+    const contains = premises[2];
+    const inherited = contains.kind === "derived" && contains.premises.length > 1;
+    return {
+      reason: `${describe(tuple[0])} reads ${String(name)} off ${describe(object)}, which contains ${describe(tuple[1])}`,
+      notes: inherited ? [`${String(name)} comes from a base class`] : []
+    };
+  },
+  "class instance": ({ tuple, premises, describe, inline }) => ({
+    reason: `${describe(tuple[0])} makes an instance of ${describe(tuple[1])}`,
+    notes: inline(premises[1])
+  }),
+  "factory unwrap": ({ tuple, premises, describe, inline }) => {
+    const factory = premises[1].tuple[1];
+    return {
+      reason: `${describe(tuple[0])} calls ${describe(factory)}, a factory that passes its argument through, so it comes down to ${describe(tuple[1])}`,
+      notes: inline(premises[1])
+    };
+  },
+  "declared wrapper": ({ tuple, premises, describe }) => {
+    const callee = String(premises[0].tuple[1]);
+    const module = String(premises[2].tuple[1]);
+    const argument = String(premises[1].tuple[1]);
+    return {
+      reason: `${describe(tuple[0])} calls ${callee} from ${module}, which passes argument ${argument} through, so it comes down to ${describe(tuple[1])}`,
+      assumptions: [
+        `a pack declares that ${callee} from ${module} passes argument ${argument} through to its result`
+      ]
+    };
+  },
+  "call result": ({ tuple, premises, describe, inline }) => {
+    const invokes = premises[0];
+    const invoked = invokes.tuple[1];
+    const calleeWalks = invokes.kind === "derived" ? invokes.premises.filter(
+      (premise) => premise.kind === "derived" && (premise.relation === "comesTo" || premise.relation === "givesBack")
+    ) : [];
+    return {
+      reason: `${describe(tuple[0])} runs ${describe(invoked)}, which returns ${describe(tuple[1])}`,
+      notes: calleeWalks.flatMap((premise) => inline(premise))
+    };
+  }
+};
+var CHAIN_RELATIONS = /* @__PURE__ */ new Set([
+  "resolves",
+  "comesTo",
+  "givesBack",
+  "isWrittenAs",
+  "comesFrom",
+  "reaches",
+  "stepsTo"
+]);
+function inlineChain(proof, state) {
+  const explained = explainResolutionProof(proof, {
+    describe: state.describe,
+    phrases: state.phrases
+  });
+  if (explained === null || explained.steps.length === 0) {
+    return [];
+  }
+  if (explained.truncated) {
+    state.truncated = true;
+  }
+  return explained.steps.map((step) => step.reason);
+}
+function stepFrom(proof, state) {
+  const name = ruleLabel(proof.rule);
+  const phrase = state.phrases[name];
+  const from = proof.tuple[0];
+  const to = proof.tuple[1];
+  if (phrase === void 0) {
+    return {
+      from,
+      to,
+      rule: name,
+      reason: `${state.describe(from)} steps to ${state.describe(to)} (${name})`,
+      notes: [],
+      assumptions: []
+    };
+  }
+  const said = phrase({
+    tuple: proof.tuple,
+    premises: proof.premises,
+    describe: state.describe,
+    inline: (nested) => inlineChain(nested, state)
+  });
+  return {
+    from,
+    to,
+    rule: name,
+    reason: said.reason,
+    notes: said.notes ?? [],
+    assumptions: said.assumptions ?? []
+  };
+}
+function importStep(proof, state) {
+  const [x, module, name] = proof.tuple;
+  return {
+    from: x,
+    to: module,
+    rule: "import",
+    reason: `${state.describe(x)} is imported from ${state.describe(module)} under the name ${String(name)}`,
+    notes: [],
+    assumptions: []
+  };
+}
+var flattenInto = (proof, state) => {
+  if (proof.kind === "truncated") {
+    state.truncated = true;
+    return;
+  }
+  if (proof.kind !== "derived") {
+    return;
+  }
+  const relation = proof.relation;
+  if (relation === "stepsTo") {
+    state.steps.push(stepFrom(proof, state));
+    return;
+  }
+  if (relation === "reaches") {
+    for (const p of proof.premises) {
+      flattenInto(p, state);
+    }
+    return;
+  }
+  if (relation === "comesFrom") {
+    if (proof.premises.length === 2) {
+      flattenInto(proof.premises[0], state);
+      state.steps.push(importStep(proof.premises[1], state));
+    } else {
+      state.steps.push(importStep(proof.premises[0], state));
+    }
+    return;
+  }
+  for (const p of proof.premises) {
+    if (p.kind === "derived" && (p.relation === "reaches" || p.relation === "comesTo")) {
+      flattenInto(p, state);
+    }
+    if (p.kind === "truncated") {
+      state.truncated = true;
+    }
+  }
+};
+function explainResolutionProof(proof, options) {
+  if (proof.kind === "absence") {
+    return null;
+  }
+  if (proof.kind === "derived" && !CHAIN_RELATIONS.has(proof.relation)) {
+    return null;
+  }
+  const state = {
+    steps: [],
+    truncated: proof.kind === "truncated",
+    describe: options.describe,
+    phrases: { ...DEFAULT_PHRASES, ...options.phrases }
+  };
+  flattenInto(proof, state);
+  const atoms = proof.kind === "fact" || proof.kind === "truncated" ? [proof.tuple[0]] : [proof.tuple[0], ...state.steps.map((step) => step.to)];
+  return {
+    atoms,
+    steps: state.steps,
+    assumptions: state.steps.flatMap((step) => step.assumptions),
+    truncated: state.truncated
+  };
+}
+function renderExplanation(explanation, describe) {
+  const lines = [];
+  if (explanation.steps.length > 0) {
+    lines.push(explanation.atoms.map((atom) => describe(atom)).join(" -> "));
+  }
+  for (const step of explanation.steps) {
+    lines.push(`  ${step.reason}`);
+    for (const note of step.notes) {
+      lines.push(`    ${note}`);
+    }
+  }
+  for (const assumption of explanation.assumptions) {
+    lines.push(`  assuming ${assumption}`);
+  }
+  if (explanation.truncated) {
+    lines.push("  the chain goes on past the proof depth cap");
+  }
+  return lines;
+}
+
 // src/index.ts
 import { constant, lit, rule, variable as v } from "@suss/datalog";
 var VALUE_STEP = constant("value");
@@ -178,14 +435,29 @@ var RESOLUTION_RULES = [
   // Aliasing: const x = y, or an identifier referencing a declaration.
   // A language with a hop of its own, like JavaScript's `.bind`, states
   // it as a step too, or every question but `comesTo` misses it.
-  rule("stepsTo", [v("x"), v("y"), VALUE_STEP], [lit("binds", v("x"), v("y"))]),
+  rule(
+    "stepsTo",
+    [v("x"), v("y"), VALUE_STEP],
+    [lit("binds", v("x"), v("y"))],
+    "alias"
+  ),
   // A name written more than once has the value the last write left
   // there. The adapter works out which write that is and stays quiet
   // when control flow decides, so such a name steps nowhere at all.
   rule(
     "stepsTo",
     [v("x"), v("y"), VALUE_STEP],
-    [lit("endsHolding", v("x"), v("y"))]
+    [lit("endsHolding", v("x"), v("y"))],
+    "last write"
+  ),
+  // A fallback says the value is one of its branches, so each branch is
+  // a step. A branch that resolves to nothing makes no claim, and two
+  // branches resolving to different things fail the single-answer policy.
+  rule(
+    "stepsTo",
+    [v("x"), v("b"), VALUE_STEP],
+    [lit("fallbackBranch", v("x"), v("b"))],
+    "fallback"
   ),
   // An import steps to what the module exports under that name.
   rule(
@@ -194,7 +466,8 @@ var RESOLUTION_RULES = [
     [
       lit("imports", v("x"), v("m"), v("n")),
       lit("moduleExport", v("m"), v("n"), v("value"))
-    ]
+    ],
+    "import"
   ),
   // A parameter steps to what a call passes it. A function called from
   // several places leaves its parameter with more than one value, and a
@@ -202,7 +475,8 @@ var RESOLUTION_RULES = [
   rule(
     "stepsTo",
     [v("p"), v("a"), VALUE_STEP],
-    [lit("passesArgument", v("r"), v("p"), v("a"))]
+    [lit("passesArgument", v("r"), v("p"), v("a"))],
+    "argument"
   ),
   // Reading a property steps to what the object contains under that
   // name, whichever way the object arrived: `routes.list` off a name,
@@ -214,7 +488,8 @@ var RESOLUTION_RULES = [
       lit("readsProperty", v("x"), v("o"), v("n")),
       lit("objectOf", v("o"), v("obj")),
       lit("contains", v("obj"), v("n"), v("held"))
-    ]
+    ],
+    "property read"
   ),
   // Calling a class makes one of it, so the call steps to the class and
   // a method read off the result is the one the class declares. The
@@ -226,7 +501,8 @@ var RESOLUTION_RULES = [
       lit("call", v("r"), v("c")),
       lit("comesTo", v("c"), v("cls")),
       lit("objectValue", v("cls"))
-    ]
+    ],
+    "class instance"
   ),
   // Wrapper transparency, derived: calling a factory that returns a
   // function which calls its parameter k steps to argument k.
@@ -238,7 +514,8 @@ var RESOLUTION_RULES = [
       lit("comesTo", v("c"), v("f")),
       lit("unwraps", v("f"), v("k")),
       lit("callArg", v("r"), v("k"), v("a"))
-    ]
+    ],
+    "factory unwrap"
   ),
   // Wrapper transparency, declared: a pack says this callee wraps
   // argument k. The callee has to come from the library the pack said,
@@ -252,14 +529,16 @@ var RESOLUTION_RULES = [
       lit("wrapperModule", v("n"), v("m")),
       lit("calleeOrigin", v("r"), v("m")),
       lit("callArg", v("r"), v("k"), v("a"))
-    ]
+    ],
+    "declared wrapper"
   ),
   // The one step that runs a function forwards: a call steps to what
   // the function it invokes returns.
   rule(
     "stepsTo",
     [v("r"), v("ret"), RESULT_STEP],
-    [lit("invokes", v("r"), v("f")), lit("returnsValue", v("f"), v("ret"))]
+    [lit("invokes", v("r"), v("f")), lit("returnsValue", v("f"), v("ret"))],
+    "call result"
   ),
   // Where a walk gets to, and whether it ran a call on the way. A value
   // step keeps whatever the rest of the walk was, and a result step
@@ -374,7 +653,8 @@ var RESOLUTION_RULES = [
   rule(
     "moduleExport",
     [v("m"), v("n"), v("value")],
-    [lit("exportsAs", v("m"), v("n"), v("value"))]
+    [lit("exportsAs", v("m"), v("n"), v("value"))],
+    "export"
   ),
   rule(
     "moduleExport",
@@ -382,7 +662,8 @@ var RESOLUTION_RULES = [
     [
       lit("reExports", v("m"), v("n"), v("m2"), v("n2")),
       lit("moduleExport", v("m2"), v("n2"), v("value"))
-    ]
+    ],
+    "re-export"
   ),
   rule(
     "moduleExport",
@@ -390,7 +671,8 @@ var RESOLUTION_RULES = [
     [
       lit("reExportsAll", v("m"), v("m2")),
       lit("moduleExport", v("m2"), v("n"), v("value"))
-    ]
+    ],
+    "re-export all"
   ),
   // The function a call runs, written from the call's side because a
   // caller asking what a call gives back has the call in hand.
@@ -642,5 +924,7 @@ export {
   RESOLUTION_RULES,
   RESULT_STEP,
   VALUE_STEP,
-  checkFactContract
+  checkFactContract,
+  explainResolutionProof,
+  renderExplanation
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/resolution",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Language-neutral rules for following a value to the function it comes down to.",
   "keywords": [
@@ -53,6 +53,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@suss/datalog": "0.10.0"
+    "@suss/datalog": "0.12.0"
   }
 }