@suss/resolution 0.21.0 → 0.22.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as _suss_datalog from '@suss/datalog';
-import { Database, Atom, Tuple, Proof } from '@suss/datalog';
+import { Database, Atom, Tuple, Proof, Rule } from '@suss/datalog';
 
 /** The tuples of one relation, as strings, which is all a case compares. */
 type FactsOf = (relation: string) => string[][];
@@ -148,6 +148,82 @@ declare function mountPathsOf(edges: MountEdges, childId: string): readonly stri
  */
 declare function agreedMountPrefix(edges: MountEdges, childId: string): string | null;
 
+/**
+ * The result shape a why session hands back, shared by every language
+ * adapter so the CLI reads one type regardless of which adapter
+ * answered. Each adapter follows its own source to a witness proof
+ * over `RESOLUTION_RULES` and renders it through `explainResolutionProof`;
+ * this is what that render comes back as.
+ *
+ * `explainResolvedKey` is the proof pass itself, for an adapter that
+ * keeps its facts in a `Database` keyed by source location: it reruns
+ * the rules with witnesses over a copy of those facts, reads the one
+ * target the asked-about key resolves to, and renders the proof. An
+ * adapter supplies how a key is said in a sentence and nothing else.
+ */
+
+/** A value or function said the way an answer prints it. */
+interface ValueLocation {
+    name: string;
+    /** Relative to the session root when under it, absolute otherwise. */
+    file: string;
+    line: number;
+}
+/** What one witness re-evaluation cost, said rather than hidden. */
+interface ExplainStats {
+    /** Facts the run had extracted, which the proof pass reran. */
+    baseFacts: number;
+    /** Facts the exhaustive pass derived on top of those. */
+    derivedFacts: number;
+    evaluateMs: number;
+}
+interface WhyExplained {
+    explanation: ResolutionExplanation;
+    /** The chain's atoms, each said in source terms. */
+    chain: string[];
+    /** The chain and its reasons as printable lines. */
+    lines: string[];
+    target: ValueLocation;
+    stats: ExplainStats;
+}
+interface ExplainResolvedKeyOptions {
+    /** The facts the session extracted. Read, never written to. */
+    db: Database;
+    /** The resolution rules plus whatever the language adds to them. */
+    rules: Rule[];
+    /** The fact key of the value asked about. */
+    key: string;
+    /** Where a fact key was written, or null for one the session never indexed. */
+    locate: (key: string) => ValueLocation | null;
+    /** How to say a key that has no location, which is a file path. */
+    displayPath: (key: string) => string;
+    maxDepth?: number;
+    phrases?: Record<string, StepPhrase>;
+}
+/**
+ * Why `key` resolves to what it does: the witness proof, flattened to
+ * the chain and rendered. Null when the key resolves to nothing or to
+ * more than one function, which the caller says in its own words.
+ */
+declare function explainResolvedKey(options: ExplainResolvedKeyOptions): WhyExplained | null;
+
+/**
+ * The single-answer policy shared by every question shaped `[key,
+ * answer]`, such as `wantedIsWrittenAs` or `wantedSubjectWritten`. A
+ * call is written as itself, so a call asked about directly always
+ * matches its own key; that row is dropped before the count so one
+ * other answer settles it instead of counting as two.
+ *
+ * A placeholder write, `client = None` before a guard fills it in, is
+ * set aside the same way when the key has any other answer. A key
+ * written only as a placeholder keeps it.
+ */
+
+/** The one answer each key settles on, once a key's match against itself is dropped. */
+declare function singleAnswers(rows: Iterable<Tuple>, placeholders?: ReadonlySet<string>): Map<string, string>;
+/** The keys an adapter marked `placeholderValue`, for passing to `singleAnswers`. */
+declare function placeholderValues(db: Database): ReadonlySet<string>;
+
 /** A step to the value x is written as. */
 declare const VALUE_STEP: _suss_datalog.Term;
 /**
@@ -196,4 +272,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, type DescribeAtom, type ExplainOptions, FACT_CONTRACT_CASES, type FactsOf, type MountEdge, type MountEdges, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ResolutionExplanation, type ResolutionStep, type StepContext, type StepPhrase, VALUE_STEP, agreedMountPrefix, checkFactContract, explainResolutionProof, joinMountedPath, mountPathsOf, renderExplanation };
+export { ANSWER_RELATIONS, type CaseFiles, type ContractCase, type ContractOptions, type DescribeAtom, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, type FactsOf, type MountEdge, type MountEdges, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ResolutionExplanation, type ResolutionStep, type StepContext, type StepPhrase, VALUE_STEP, type ValueLocation, type WhyExplained, agreedMountPrefix, checkFactContract, explainResolutionProof, explainResolvedKey, joinMountedPath, mountPathsOf, placeholderValues, renderExplanation, singleAnswers };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _suss_datalog from '@suss/datalog';
-import { Database, Atom, Tuple, Proof } from '@suss/datalog';
+import { Database, Atom, Tuple, Proof, Rule } from '@suss/datalog';
 
 /** The tuples of one relation, as strings, which is all a case compares. */
 type FactsOf = (relation: string) => string[][];
@@ -148,6 +148,82 @@ declare function mountPathsOf(edges: MountEdges, childId: string): readonly stri
  */
 declare function agreedMountPrefix(edges: MountEdges, childId: string): string | null;
 
+/**
+ * The result shape a why session hands back, shared by every language
+ * adapter so the CLI reads one type regardless of which adapter
+ * answered. Each adapter follows its own source to a witness proof
+ * over `RESOLUTION_RULES` and renders it through `explainResolutionProof`;
+ * this is what that render comes back as.
+ *
+ * `explainResolvedKey` is the proof pass itself, for an adapter that
+ * keeps its facts in a `Database` keyed by source location: it reruns
+ * the rules with witnesses over a copy of those facts, reads the one
+ * target the asked-about key resolves to, and renders the proof. An
+ * adapter supplies how a key is said in a sentence and nothing else.
+ */
+
+/** A value or function said the way an answer prints it. */
+interface ValueLocation {
+    name: string;
+    /** Relative to the session root when under it, absolute otherwise. */
+    file: string;
+    line: number;
+}
+/** What one witness re-evaluation cost, said rather than hidden. */
+interface ExplainStats {
+    /** Facts the run had extracted, which the proof pass reran. */
+    baseFacts: number;
+    /** Facts the exhaustive pass derived on top of those. */
+    derivedFacts: number;
+    evaluateMs: number;
+}
+interface WhyExplained {
+    explanation: ResolutionExplanation;
+    /** The chain's atoms, each said in source terms. */
+    chain: string[];
+    /** The chain and its reasons as printable lines. */
+    lines: string[];
+    target: ValueLocation;
+    stats: ExplainStats;
+}
+interface ExplainResolvedKeyOptions {
+    /** The facts the session extracted. Read, never written to. */
+    db: Database;
+    /** The resolution rules plus whatever the language adds to them. */
+    rules: Rule[];
+    /** The fact key of the value asked about. */
+    key: string;
+    /** Where a fact key was written, or null for one the session never indexed. */
+    locate: (key: string) => ValueLocation | null;
+    /** How to say a key that has no location, which is a file path. */
+    displayPath: (key: string) => string;
+    maxDepth?: number;
+    phrases?: Record<string, StepPhrase>;
+}
+/**
+ * Why `key` resolves to what it does: the witness proof, flattened to
+ * the chain and rendered. Null when the key resolves to nothing or to
+ * more than one function, which the caller says in its own words.
+ */
+declare function explainResolvedKey(options: ExplainResolvedKeyOptions): WhyExplained | null;
+
+/**
+ * The single-answer policy shared by every question shaped `[key,
+ * answer]`, such as `wantedIsWrittenAs` or `wantedSubjectWritten`. A
+ * call is written as itself, so a call asked about directly always
+ * matches its own key; that row is dropped before the count so one
+ * other answer settles it instead of counting as two.
+ *
+ * A placeholder write, `client = None` before a guard fills it in, is
+ * set aside the same way when the key has any other answer. A key
+ * written only as a placeholder keeps it.
+ */
+
+/** The one answer each key settles on, once a key's match against itself is dropped. */
+declare function singleAnswers(rows: Iterable<Tuple>, placeholders?: ReadonlySet<string>): Map<string, string>;
+/** The keys an adapter marked `placeholderValue`, for passing to `singleAnswers`. */
+declare function placeholderValues(db: Database): ReadonlySet<string>;
+
 /** A step to the value x is written as. */
 declare const VALUE_STEP: _suss_datalog.Term;
 /**
@@ -196,4 +272,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, type DescribeAtom, type ExplainOptions, FACT_CONTRACT_CASES, type FactsOf, type MountEdge, type MountEdges, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ResolutionExplanation, type ResolutionStep, type StepContext, type StepPhrase, VALUE_STEP, agreedMountPrefix, checkFactContract, explainResolutionProof, joinMountedPath, mountPathsOf, renderExplanation };
+export { ANSWER_RELATIONS, type CaseFiles, type ContractCase, type ContractOptions, type DescribeAtom, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, type FactsOf, type MountEdge, type MountEdges, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ResolutionExplanation, type ResolutionStep, type StepContext, type StepPhrase, VALUE_STEP, type ValueLocation, type WhyExplained, agreedMountPrefix, checkFactContract, explainResolutionProof, explainResolvedKey, joinMountedPath, mountPathsOf, placeholderValues, renderExplanation, singleAnswers };

package/dist/index.js

@@ -477,6 +477,93 @@ function pathsOf(edges, memo, childId, visiting) {
   return result;
 }
 
+// src/session.ts
+import { Database, evaluate, proofOf, witnesses } from "@suss/datalog";
+function explainResolvedKey(options) {
+  const { db, rules, key, locate, displayPath } = options;
+  const proofDb = new Database();
+  let baseFacts = 0;
+  for (const relation of db.relationNames()) {
+    for (const tuple of db.facts(relation)) {
+      proofDb.add(relation, tuple);
+      baseFacts++;
+    }
+  }
+  const started = performance.now();
+  evaluate(proofDb, rules, witnesses);
+  const evaluateMs = performance.now() - started;
+  const derivedFacts = proofDb.relationNames().reduce((count, relation) => count + proofDb.size(relation), 0) - baseFacts;
+  const targets = new Set(
+    proofDb.lookup("resolves", 0, key).map((tuple) => String(tuple[1]))
+  );
+  if (targets.size !== 1) {
+    return null;
+  }
+  const target = [...targets][0];
+  const proof = proofOf(
+    proofDb,
+    "resolves",
+    [key, target],
+    options.maxDepth === void 0 ? {} : { maxDepth: options.maxDepth }
+  );
+  const describe = (atom) => {
+    const location = locate(String(atom));
+    return location === null ? displayPath(String(atom)) : `${location.name} (${location.file}:${location.line})`;
+  };
+  const explanation = explainResolutionProof(proof, {
+    describe,
+    ...options.phrases === void 0 ? {} : { phrases: options.phrases }
+  });
+  if (explanation === null) {
+    return null;
+  }
+  const targetLocation = locate(target);
+  if (targetLocation === null) {
+    return null;
+  }
+  return {
+    explanation,
+    chain: explanation.atoms.map(describe),
+    lines: renderExplanation(explanation, describe),
+    target: targetLocation,
+    stats: { baseFacts, derivedFacts, evaluateMs }
+  };
+}
+
+// src/singleAnswer.ts
+var NO_PLACEHOLDERS = /* @__PURE__ */ new Set();
+function singleAnswers(rows, placeholders = NO_PLACEHOLDERS) {
+  const candidates = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = String(row[0]);
+    const answer = String(row[1]);
+    if (answer === key) {
+      continue;
+    }
+    const set = candidates.get(key) ?? /* @__PURE__ */ new Set();
+    set.add(answer);
+    candidates.set(key, set);
+  }
+  const settled = /* @__PURE__ */ new Map();
+  for (const [key, set] of candidates) {
+    const answers = withoutPlaceholders(set, placeholders);
+    if (answers.length === 1) {
+      settled.set(key, answers[0]);
+    }
+  }
+  return settled;
+}
+function placeholderValues(db) {
+  return new Set(db.facts("placeholderValue").map((row) => String(row[0])));
+}
+function withoutPlaceholders(answers, placeholders) {
+  const kept = [...answers].filter((answer) => !placeholders.has(answer));
+  if (kept.length === 0) {
+    return [...answers];
+  }
+  return kept;
+}
+
 // src/index.ts
 import { constant, lit, rule, variable as v } from "@suss/datalog";
 var VALUE_STEP = constant("value");
@@ -592,9 +679,9 @@ var RESOLUTION_RULES = [
     [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
-  // makes the whole walk one that ran a call.
+  // Where a walk gets to, and whether it ran a call on the way. The walk
+  // so far comes first, so demand stays on the value asked about; the
+  // README says what the other order cost.
   rule(
     "reaches",
     [v("x"), v("z"), v("kind")],
@@ -604,27 +691,27 @@ var RESOLUTION_RULES = [
     "reaches",
     [v("x"), v("z"), v("kind")],
     [
-      lit("stepsTo", v("x"), v("y"), VALUE_STEP),
-      lit("reaches", v("y"), v("z"), v("kind"))
+      lit("reaches", v("x"), v("y"), VALUE_STEP),
+      lit("stepsTo", v("y"), v("z"), v("kind"))
     ]
   ),
-  // Two rules rather than one leaving the rest of the walk's kind free.
-  // A free kind is a second question about the same relation, and a
+  // Two rules rather than one leaving the next step's kind free. A free
+  // kind is a second question about the same relation, and a
   // demand-driven run then derives both to answer either.
   rule(
     "reaches",
     [v("x"), v("z"), RESULT_STEP],
     [
-      lit("stepsTo", v("x"), v("y"), RESULT_STEP),
-      lit("reaches", v("y"), v("z"), VALUE_STEP)
+      lit("reaches", v("x"), v("y"), RESULT_STEP),
+      lit("stepsTo", v("y"), v("z"), VALUE_STEP)
     ]
   ),
   rule(
     "reaches",
     [v("x"), v("z"), RESULT_STEP],
     [
-      lit("stepsTo", v("x"), v("y"), RESULT_STEP),
-      lit("reaches", v("y"), v("z"), RESULT_STEP)
+      lit("reaches", v("x"), v("y"), RESULT_STEP),
+      lit("stepsTo", v("y"), v("z"), RESULT_STEP)
     ]
   ),
   // What a value comes down to: the walk that never ran a call, stopped
@@ -670,6 +757,18 @@ var RESOLUTION_RULES = [
     [v("x"), v("z")],
     [lit("reaches", v("x"), v("z"), VALUE_STEP), lit("objectValue", v("z"))]
   ),
+  // A call is written as whatever its callee's return value is written
+  // as. Unlike `comesTo`, this has nothing to protect: which expression
+  // a value was written as does not compete with unwrapping it.
+  rule(
+    "isWrittenAs",
+    [v("x"), v("z")],
+    [
+      lit("invokes", v("x"), v("f")),
+      lit("returnsValue", v("f"), v("ret")),
+      lit("isWrittenAs", v("ret"), v("z"))
+    ]
+  ),
   // What one call site put in a parameter, told apart from what the
   // other callers passed.
   rule(
@@ -970,29 +1069,14 @@ var RESOLUTION_QUESTIONS = [
   // here demands reaches or callsInto. The chains are closures with
   // no depth bound: an alias run of any length resolves.
   rule("callOriginChain", [v("x"), v("x")], [lit("wantedCallOrigin", v("x"))]),
+  // The chain with at least one hop taken, which is what tells a
+  // destructured binding apart from asking about a node directly. The
+  // whole chain is the seed plus those hops.
   rule(
     "callOriginChain",
     [v("x"), v("z")],
-    [lit("callOriginChain", v("x"), v("y")), lit("binds", v("y"), v("z"))]
-  ),
-  rule(
-    "callOriginChain",
-    [v("x"), v("z")],
-    [
-      lit("callOriginChain", v("x"), v("y")),
-      lit("endsHolding", v("y"), v("z"))
-    ]
-  ),
-  rule(
-    "callOriginChain",
-    [v("x"), v("z")],
-    [
-      lit("callOriginChain", v("x"), v("y")),
-      lit("fallbackBranch", v("y"), v("z"))
-    ]
+    [lit("callOriginChainStepped", v("x"), v("z"))]
   ),
-  // The chain with at least one hop taken, which is what tells a
-  // destructured binding apart from asking about a node directly.
   rule(
     "callOriginChainStepped",
     [v("x"), v("z")],
@@ -1231,7 +1315,10 @@ export {
   agreedMountPrefix,
   checkFactContract,
   explainResolutionProof,
+  explainResolvedKey,
   joinMountedPath,
   mountPathsOf,
-  renderExplanation
+  placeholderValues,
+  renderExplanation,
+  singleAnswers
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/resolution",
-  "version": "0.21.0",
+  "version": "0.22.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.21.0"
+    "@suss/datalog": "0.22.0"
   }
 }