@suss/resolution 0.21.1 → 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");
@@ -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(
@@ -1216,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.1",
+  "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.1"
+    "@suss/datalog": "0.22.0"
   }
 }