@suss/resolution 0.27.0 → 0.29.0

package/dist/index.js

@@ -1,3 +1,263 @@
+// src/program.ts
+import { clearRelations, deriveOnDemand, evaluate } from "@suss/datalog";
+var ASKING_RELATIONS = [
+  "wanted",
+  "wantedOrigin",
+  "wantedCallOrigin",
+  "wantedExportsOf",
+  "wantedSubject",
+  "wantedAnchor",
+  "wantedAncestry"
+];
+var NO_LANGUAGE_RULES = [];
+var programs = /* @__PURE__ */ new WeakMap();
+function resolutionProgram(languageRules = NO_LANGUAGE_RULES) {
+  const built = programs.get(languageRules);
+  if (built !== void 0) {
+    return built;
+  }
+  const rules = [
+    ...RESOLUTION_RULES,
+    ...languageRules,
+    ...RESOLUTION_QUESTIONS
+  ];
+  const program = process.env.SUSS_RESOLUTION_ON_DEMAND === "0" ? { rules, demandDriven: [], demands: [] } : deriveOnDemand(rules, ANSWER_RELATIONS);
+  programs.set(languageRules, program);
+  return program;
+}
+function queryFacts(program) {
+  if (program.demandDriven.length === 0) {
+    return [];
+  }
+  return [...program.demandDriven, ...ASKING_RELATIONS];
+}
+var askedByDb = /* @__PURE__ */ new WeakMap();
+function askedOf(db, asking) {
+  let byRelation = askedByDb.get(db);
+  if (byRelation === void 0) {
+    byRelation = /* @__PURE__ */ new Map();
+    askedByDb.set(db, byRelation);
+  }
+  let asked = byRelation.get(asking);
+  if (asked === void 0) {
+    asked = /* @__PURE__ */ new Set();
+    byRelation.set(asking, asked);
+  }
+  return asked;
+}
+function askResolution(db, keys, asking = "wanted", program = resolutionProgram()) {
+  const asked = askedOf(db, asking);
+  const fresh = [...keys].filter((key) => !asked.has(key));
+  if (fresh.length === 0) {
+    return;
+  }
+  for (const key of fresh) {
+    asked.add(key);
+    db.add(asking, [key]);
+  }
+  evaluate(db, program.rules);
+  const forget = queryFacts(program);
+  if (forget.length > 0) {
+    clearRelations(db, program.rules, forget);
+  }
+}
+
+// src/callee.ts
+var UNDECLARED = { kind: "undeclared" };
+var UNSETTLED = { kind: "unsettled" };
+var OUTSIDE_RUN = { kind: "outsideRun" };
+function calleeOutcomes(db, keys, program = resolutionProgram()) {
+  askAboutSources(db, keys, program);
+  const reading = new Reading(db);
+  const outcomes = /* @__PURE__ */ new Map();
+  for (const key of keys) {
+    outcomes.set(key, reading.outcomeOf(key));
+  }
+  return outcomes;
+}
+function calleeOutcomeOf(db, key, program = resolutionProgram()) {
+  return calleeOutcomes(db, [key], program).get(key) ?? UNDECLARED;
+}
+function askAboutSources(db, keys, program) {
+  let wave = [...new Set(keys)];
+  const asked = new Set(wave);
+  while (wave.length > 0) {
+    askResolution(db, wave, "wanted", program);
+    const next = [];
+    for (const key of wave) {
+      if (!decidedByCallers(db, key) && answersFor(db, key).length > 0) {
+        continue;
+      }
+      for (const source of sourcesOf(db, key)) {
+        if (!asked.has(source)) {
+          asked.add(source);
+          next.push(source);
+        }
+      }
+    }
+    wave = next;
+  }
+}
+function couldBeSettled(db, key) {
+  return db.has("func", [key]) || db.has("objectValue", [key]) || sourcesOf(db, key).length > 0;
+}
+function sourcesOf(db, key) {
+  const base = db.lookup("readsProperty", 0, key)[0];
+  if (base !== void 0) {
+    return [String(base[1])];
+  }
+  const call = db.lookup("call", 0, key)[0];
+  if (call !== void 0) {
+    return [String(call[1])];
+  }
+  return writtenSourcesOf(db, key);
+}
+var WRITE_RELATIONS = ["binds", "endsHolding", "mayHold"];
+function writtenSourcesOf(db, key) {
+  const found = [];
+  for (const relation of WRITE_RELATIONS) {
+    for (const row of db.lookup(relation, 0, key)) {
+      found.push(String(row[1]));
+    }
+  }
+  return found;
+}
+function answersFor(db, key) {
+  const found = /* @__PURE__ */ new Map();
+  for (const row of db.lookup("wantedComesTo", 0, key)) {
+    const answer = String(row[1]);
+    if (db.has("func", [answer])) {
+      found.set(answer, { kind: "function", key: answer });
+      continue;
+    }
+    if (db.has("objectValue", [answer])) {
+      found.set(answer, { kind: "object", key: answer });
+    }
+  }
+  return [...found.values()];
+}
+function outcomeKey(outcome) {
+  if (outcome.kind === "function" || outcome.kind === "object") {
+    return `${outcome.kind}:${outcome.key}`;
+  }
+  return outcome.kind;
+}
+var THROUGH_BASE = {
+  function: UNDECLARED,
+  object: UNDECLARED
+};
+var THROUGH_CALL = {
+  function: UNSETTLED,
+  object: UNSETTLED
+};
+var Reading = class {
+  constructor(db) {
+    this.db = db;
+  }
+  db;
+  memo = /* @__PURE__ */ new Map();
+  walking = /* @__PURE__ */ new Set();
+  outcomeOf(key) {
+    return this.walk(key).outcome;
+  }
+  walk(key) {
+    const known = this.memo.get(key);
+    if (known !== void 0) {
+      return { outcome: known, looped: false };
+    }
+    if (this.walking.has(key)) {
+      return { outcome: UNDECLARED, looped: true };
+    }
+    this.walking.add(key);
+    const found = this.decide(key);
+    this.walking.delete(key);
+    if (!found.looped) {
+      this.memo.set(key, found.outcome);
+    }
+    return found;
+  }
+  decide(key) {
+    if (decidedByCallers(this.db, key)) {
+      return this.fromWrites(key);
+    }
+    const answers = answersFor(this.db, key);
+    if (answers.length > 1) {
+      return {
+        outcome: { kind: "severalSources", sources: answers.map(outcomeKey) },
+        looped: false
+      };
+    }
+    const only = answers[0];
+    if (only !== void 0) {
+      return { outcome: only, looped: false };
+    }
+    return this.refusal(key);
+  }
+  refusal(key) {
+    const base = this.db.lookup("readsProperty", 0, key)[0];
+    if (base !== void 0) {
+      return this.through(THROUGH_BASE, String(base[1]));
+    }
+    const call = this.db.lookup("call", 0, key)[0];
+    if (call !== void 0) {
+      return this.through(THROUGH_CALL, String(call[1]));
+    }
+    return this.fromWrites(key);
+  }
+  through(table, source) {
+    const found = this.walk(source);
+    return {
+      outcome: table[found.outcome.kind] ?? found.outcome,
+      looped: found.looped
+    };
+  }
+  /**
+   * What the writes to a name, and the arguments a call put in a
+   * parameter, agree the value is. A source that says nothing is left
+   * out, so a name narrowed through a second name keeps the outcome it
+   * started with rather than counting as a second source.
+   */
+  fromWrites(key) {
+    const found = /* @__PURE__ */ new Map();
+    let looped = false;
+    for (const source of writtenSourcesOf(this.db, key)) {
+      const from = this.walk(source);
+      looped = looped || from.looped;
+      if (from.outcome.kind !== "undeclared") {
+        found.set(outcomeKey(from.outcome), from.outcome);
+      }
+    }
+    if (isParameter(this.db, key)) {
+      found.set("callerSupplied", { kind: "callerSupplied", key });
+    }
+    if (found.size > 1) {
+      return {
+        outcome: { kind: "severalSources", sources: [...found.keys()] },
+        looped
+      };
+    }
+    const only = [...found.values()][0];
+    return { outcome: only ?? whereItCameFrom(this.db, key), looped };
+  }
+};
+function isParameter(db, key) {
+  return db.lookup("paramNamed", 2, key).length > 0 || db.lookup("paramOf", 2, key).length > 0;
+}
+function decidedByCallers(db, key) {
+  return isParameter(db, key) && db.lookup("binds", 0, key).length === 0;
+}
+function whereItCameFrom(db, key) {
+  for (const row of db.lookup("imports", 0, key)) {
+    if (db.lookup("exportsAs", 0, String(row[1])).length === 0) {
+      return OUTSIDE_RUN;
+    }
+  }
+  if (db.has("writtenValue", [key])) {
+    return OUTSIDE_RUN;
+  }
+  return db.has("writesUnstated", [key]) ? UNSETTLED : UNDECLARED;
+}
+
 // src/contract.ts
 var distinct = (values) => new Set(values).size;
 var RELATIONS_THAT_CAN_CROSS = ["imports", "binds", "reExports"];
@@ -273,6 +533,38 @@ var DEFAULT_PHRASES = {
       ]
     };
   },
+  "declared finder": ({ tuple, premises, describe }) => {
+    const method = String(premises[1].tuple[2]);
+    const base = String(premises[4].tuple[0]);
+    return {
+      reason: `${describe(tuple[0])} calls ${method} on ${describe(tuple[1])}, which gives back one of it`,
+      assumptions: [
+        `a pack declares that ${method} on a class extending ${base} gives back one of that class`
+      ]
+    };
+  },
+  "declared argument finder": ({ tuple, premises, describe }) => {
+    const method = String(premises[1].tuple[2]);
+    const position = String(premises[2].tuple[1]);
+    const base = String(premises[3].tuple[0]);
+    return {
+      reason: `${describe(tuple[0])} calls ${method} with ${describe(tuple[1])} at argument ${position}, which gives back one of it`,
+      assumptions: [
+        `a pack declares that ${method} with a class extending ${base} at argument ${position} gives back one of that class`
+      ]
+    };
+  },
+  "declared import finder": ({ tuple, premises, describe }) => {
+    const module = String(premises[1].tuple[1]);
+    const name = String(premises[1].tuple[2]);
+    const position = String(premises[2].tuple[2]);
+    return {
+      reason: `${describe(tuple[0])} calls ${name} from ${module} with ${describe(tuple[1])} at argument ${position}, which gives back one of it`,
+      assumptions: [
+        `a pack declares that ${name} from ${module} gives back one of the class at argument ${position}`
+      ]
+    };
+  },
   "call result": ({ tuple, premises, describe, inline }) => {
     const invokes = premises[0];
     const invoked = invokes.tuple[1];
@@ -477,6 +769,47 @@ function pathsOf(edges, memo, childId, visiting) {
   return result;
 }
 
+// src/nameReads.ts
+function writesRunInOrder(scope, name, writes, rules) {
+  const last = writes[writes.length - 1];
+  if (scope === null || last === void 0) {
+    return false;
+  }
+  if (!writes.every((write) => write.direct)) {
+    return false;
+  }
+  return !isReadBefore(scope, name, last.at.startIndex, rules);
+}
+function isReadBefore(scope, name, position, rules) {
+  let found = false;
+  const visit = (node) => {
+    if (found || node.startIndex >= position) {
+      return;
+    }
+    if (rules.laterBodies.has(node.type)) {
+      return;
+    }
+    if (rules.nameTypes.has(node.type) && node.text === name) {
+      found = rules.isRead(node);
+      return;
+    }
+    for (const child of rules.childrenOf(node)) {
+      visit(child);
+    }
+  };
+  for (const child of rules.childrenOf(scope)) {
+    visit(child);
+  }
+  return found;
+}
+function startsAtName(node, name, rules) {
+  if (rules.nameTypes.has(node.type)) {
+    return node.text === name;
+  }
+  const inner = rules.readFirst(node);
+  return inner !== null && startsAtName(inner, name, rules);
+}
+
 // src/nodeKey.ts
 var SPAN_KEY = /^(.*):(\d+)-(\d+)$/;
 function nodeOfKey(rootsByFile, key) {
@@ -504,7 +837,7 @@ function nodeOfKey(rootsByFile, key) {
 }
 
 // src/session.ts
-import { Database, evaluate, proofOf, witnesses } from "@suss/datalog";
+import { Database, evaluate as evaluate2, proofOf, witnesses } from "@suss/datalog";
 function explainResolvedKey(options) {
   const { db, rules, key, locate, displayPath } = options;
   const proofDb = new Database();
@@ -516,7 +849,7 @@ function explainResolvedKey(options) {
     }
   }
   const started = performance.now();
-  evaluate(proofDb, rules, witnesses);
+  evaluate2(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(
@@ -590,6 +923,35 @@ function withoutPlaceholders(answers, placeholders) {
   return kept;
 }
 
+// src/writes.ts
+function valueLeftByWrites(writes, ordered) {
+  const deciding = writes.filter((write) => !write.narrowsName);
+  const left = deciding.length === 0 ? writes : deciding;
+  if (left.some((write) => write.value === null)) {
+    return null;
+  }
+  if (ordered) {
+    return left[left.length - 1]?.value ?? null;
+  }
+  return sharedConstruction(left);
+}
+function sharedConstruction(writes) {
+  let settled = null;
+  for (const write of writes) {
+    if (write.placeholder) {
+      continue;
+    }
+    if (write.construction === null) {
+      return null;
+    }
+    if (settled !== null && write.construction !== settled.construction) {
+      return null;
+    }
+    settled = write;
+  }
+  return settled?.value ?? null;
+}
+
 // src/writtenValue.ts
 function writtenValueOf(db, key, ask) {
   const placeholders = placeholderValues(db);
@@ -689,6 +1051,57 @@ var RESOLUTION_RULES = [
     ],
     "class instance"
   ),
+  // A finder the library declares, keyed on the base a pack named so a
+  // project class with a method of the same name on another hierarchy is
+  // left alone. The DESIGN says what a chain of them composes into.
+  rule(
+    "stepsTo",
+    [v("r"), v("cls"), VALUE_STEP],
+    [
+      lit("call", v("r"), v("c")),
+      lit("readsProperty", v("c"), v("o"), v("m")),
+      lit("objectOf", v("o"), v("cls")),
+      lit("objectValue", v("cls")),
+      // Before `libraryBase`, so the demand rewrite asks it with the base
+      // bound and walks an ancestry only for a method a pack declared.
+      lit("givesBackOne", v("n"), v("m")),
+      lit("libraryBase", v("cls"), v("n"))
+    ],
+    "declared finder"
+  ),
+  // The same word, for a library that takes the class as an argument
+  // instead of as the receiver. The argument having to reach the base a
+  // pack named is what keeps an unrelated `get` out.
+  rule(
+    "stepsTo",
+    [v("r"), v("cls"), VALUE_STEP],
+    [
+      lit("call", v("r"), v("c")),
+      lit("readsProperty", v("c"), v("o"), v("m")),
+      lit("callArg", v("r"), v("k"), v("a")),
+      // Before `libraryBase`, so the demand rewrite asks it with the base
+      // bound and walks an ancestry only for a method a pack declared.
+      lit("givesBackOneOfArgument", v("n"), v("m"), v("k")),
+      lit("objectOf", v("a"), v("cls")),
+      lit("libraryBase", v("cls"), v("n"))
+    ],
+    "declared argument finder"
+  ),
+  // The same again for a function called on its own rather than read off
+  // anything, keyed on the module it was imported from so a project
+  // function spelled the same way is not mistaken for it.
+  rule(
+    "stepsTo",
+    [v("r"), v("cls"), VALUE_STEP],
+    [
+      lit("call", v("r"), v("c")),
+      lit("comesFrom", v("c"), v("mod"), v("n")),
+      lit("givesBackOneOfImport", v("mod"), v("n"), v("k")),
+      lit("callArg", v("r"), v("k"), v("a")),
+      lit("objectOf", v("a"), v("cls"))
+    ],
+    "declared import finder"
+  ),
   // Wrapper transparency, derived: calling a factory that returns a
   // function which calls its parameter k steps to argument k.
   rule(
@@ -962,6 +1375,32 @@ var RESOLUTION_RULES = [
       lit("contains", v("baseCls"), v("n"), v("held"))
     ]
   ),
+  // The library base a class's ancestry arrives at, however many of a
+  // project's own classes sit in between. A base the run declares has a
+  // node to keep walking from; one it does not has only a name.
+  rule("libraryBase", [v("c"), v("n")], [lit("extendsNamed", v("c"), v("n"))]),
+  rule(
+    "libraryBase",
+    [v("c"), v("n")],
+    [
+      lit("extends", v("c"), v("x")),
+      lit("comesTo", v("x"), v("b")),
+      lit("libraryBase", v("b"), v("n"))
+    ]
+  ),
+  // A base a library hands back from a call rather than exporting as a
+  // class, SQLAlchemy's `Base = declarative_base()`. The walk stops at
+  // the call, so the function it called is the name to match on.
+  rule(
+    "libraryBase",
+    [v("c"), v("n")],
+    [
+      lit("extends", v("c"), v("x")),
+      lit("isWrittenAs", v("x"), v("r")),
+      lit("call", v("r"), v("cc")),
+      lit("comesFrom", v("cc"), v("m"), v("n"))
+    ]
+  ),
   // Which function a factory returns, and which of its parameters that
   // function calls: together they are what makes it a wrapper.
   rule(
@@ -1310,6 +1749,17 @@ var RESOLUTION_QUESTIONS = [
     [v("c"), v("n")],
     [lit("ancestryChain", v("c"), v("b")), lit("extendsNamed", v("b"), v("n"))]
   ),
+  // Each method the same chain declares, so a caller that settled a
+  // receiver on a class can tell a method the project writes itself
+  // from one only the library provides.
+  rule(
+    "wantedDeclaredName",
+    [v("c"), v("n")],
+    [
+      lit("ancestryChain", v("c"), v("b")),
+      lit("holdsProperty", v("b"), v("n"), v("held"))
+    ]
+  ),
   rule("anchorChain", [v("x"), v("x")], [lit("wantedAnchor", v("x"))]),
   rule(
     "anchorChain",
@@ -1359,6 +1809,7 @@ var ANSWER_RELATIONS = [
 ];
 export {
   ANSWER_RELATIONS,
+  ASKING_RELATIONS,
   FACT_CONTRACT_CASES,
   NAMESPACE_IMPORT,
   NAMESPACE_IMPORT_NAME,
@@ -1367,14 +1818,24 @@ export {
   RESULT_STEP,
   VALUE_STEP,
   agreedMountPrefix,
+  askResolution,
+  calleeOutcomeOf,
+  calleeOutcomes,
   checkFactContract,
+  couldBeSettled,
   explainResolutionProof,
   explainResolvedKey,
   joinMountedPath,
   mountPathsOf,
   nodeOfKey,
   placeholderValues,
+  queryFacts,
   renderExplanation,
+  resolutionProgram,
   singleAnswers,
+  startsAtName,
+  valueLeftByWrites,
+  writesRunInOrder,
+  writtenSourcesOf,
   writtenValueOf
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/resolution",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "type": "module",
   "description": "The rules suss uses to follow a name in TypeScript, Python or Ruby to the function it comes down to.",
   "keywords": [
@@ -56,6 +56,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@suss/datalog": "0.27.0"
+    "@suss/datalog": "0.29.0"
   }
 }