@suss/resolution 0.27.0 → 0.28.0

package/dist/index.js

@@ -1,3 +1,260 @@
+// 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 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"];
@@ -477,6 +734,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 +802,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 +814,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 +888,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);
@@ -1359,6 +1686,7 @@ var ANSWER_RELATIONS = [
 ];
 export {
   ANSWER_RELATIONS,
+  ASKING_RELATIONS,
   FACT_CONTRACT_CASES,
   NAMESPACE_IMPORT,
   NAMESPACE_IMPORT_NAME,
@@ -1367,6 +1695,9 @@ export {
   RESULT_STEP,
   VALUE_STEP,
   agreedMountPrefix,
+  askResolution,
+  calleeOutcomeOf,
+  calleeOutcomes,
   checkFactContract,
   explainResolutionProof,
   explainResolvedKey,
@@ -1374,7 +1705,13 @@ export {
   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.28.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.28.0"
   }
 }