@suss/resolution 0.32.0 → 0.33.0

package/README.md

@@ -21,7 +21,7 @@ and a handler factory in TypeScript.
 ## More
 
 - [How the rules follow a value](./DESIGN.md)
-- [Documentation](https://nimbuscloud-ai.github.io/suss/)
+- [Documentation](https://suss.sh/)
 - [Source and issues](https://github.com/nimbuscloud-ai/suss)
 
 ![coverage](../../.github/badges/coverage-resolution.svg)

package/dist/index.cjs

@@ -80,7 +80,7 @@ var ASKING_RELATIONS = [
   "wanted",
   "wantedUnder",
   "wantedSites",
-  "wantedEnvSite",
+  "wantedEnvObject",
   "wantedOrigin",
   "wantedCallOrigin",
   "wantedExportsOf",
@@ -1120,6 +1120,16 @@ function answersByKey(rows, placeholders = NO_PLACEHOLDERS) {
   }
   return answers;
 }
+function answersFor2(db, relation, key) {
+  const rows = db.lookup(relation, 0, key);
+  if (rows.length === 0) {
+    return [];
+  }
+  const placeholders = new Set(
+    rows.map((row) => String(row[1])).filter((answer) => db.has("placeholderValue", [answer]))
+  );
+  return answersByKey(rows, placeholders).get(key) ?? [];
+}
 function singleAnswers(rows, placeholders = NO_PLACEHOLDERS) {
   const settled = /* @__PURE__ */ new Map();
   for (const [key, answers] of answersByKey(rows, placeholders)) {
@@ -1211,38 +1221,42 @@ function writtenValuesByKey(db, keys, ask, relation = WRITTEN_AS) {
   return one;
 }
 function settledByKey(db, keys, ask, relation) {
-  const placeholders = placeholderValues(db);
-  const byKey = answersByKey(db.facts(relation), placeholders);
-  const direct = new Map(keys.map((key) => [key, byKey.get(key) ?? []]));
-  const calls = new Set(db.facts("call").map((row) => String(row[0])));
-  const throughCalls = [...direct.values()].flat().filter((answer) => calls.has(answer));
+  const direct = new Map(
+    keys.map((key) => [key, answersFor2(db, relation, key)])
+  );
+  const throughCalls = [...direct.values()].flat().filter((answer) => isCall(db, answer));
   if (throughCalls.length === 0) {
     return direct;
   }
   ask(throughCalls);
-  const deeper = singleAnswers(db.facts(relation), placeholders);
   return new Map(
     [...direct].map(([key, answers]) => [
       key,
-      collapseCalls(answers, calls, deeper)
+      collapseCalls(db, relation, answers)
     ])
   );
 }
-function collapseCalls(direct, calls, deeper) {
+function isCall(db, key) {
+  return db.lookup("call", 0, key).length > 0;
+}
+function collapseCalls(db, relation, direct) {
   return [
     ...new Set(
       direct.map(
-        (answer) => calls.has(answer) ? deeper.get(answer) ?? answer : answer
+        (answer) => isCall(db, answer) ? behindCall(db, relation, answer) : answer
       )
     )
   ];
 }
+function behindCall(db, relation, call) {
+  const answers = answersFor2(db, relation, call);
+  return answers.length === 1 ? answers[0] : call;
+}
 function writesLeft(db, key) {
-  const unstated = db.facts("writesUnstated").some((row) => String(row[0]) === key);
-  if (unstated) {
+  if (db.has("writesUnstated", [key])) {
     return [];
   }
-  const candidates = answersByKey(db.facts("mayHold"), placeholderValues(db)).get(key) ?? [];
+  const candidates = answersFor2(db, "mayHold", key);
   return candidates.length > 1 ? candidates : [];
 }
 
@@ -2013,6 +2027,51 @@ var STATED_RULES = [
     [(0, import_datalog4.variable)("x"), (0, import_datalog4.variable)("p")],
     [(0, import_datalog4.lit)("refersToParam", (0, import_datalog4.variable)("y"), (0, import_datalog4.variable)("p")), (0, import_datalog4.lit)("binds", (0, import_datalog4.variable)("x"), (0, import_datalog4.variable)("y"))]
   ),
+  // An expression whose value is the environment object w: the way a
+  // pack spells it, a name declared as that, or a parameter a caller
+  // handed one of those to, however many calls deep.
+  (0, import_datalog4.rule)(
+    "environmentValue",
+    [(0, import_datalog4.variable)("w"), (0, import_datalog4.variable)("o")],
+    [(0, import_datalog4.lit)("environmentObject", (0, import_datalog4.variable)("w")), (0, import_datalog4.lit)("refersToObject", (0, import_datalog4.variable)("o"), (0, import_datalog4.variable)("w"))]
+  ),
+  (0, import_datalog4.rule)(
+    "environmentValue",
+    [(0, import_datalog4.variable)("w"), (0, import_datalog4.variable)("o")],
+    [
+      (0, import_datalog4.lit)("environmentValue", (0, import_datalog4.variable)("w"), (0, import_datalog4.variable)("a")),
+      (0, import_datalog4.lit)("passesArgument", (0, import_datalog4.variable)("r"), (0, import_datalog4.variable)("p"), (0, import_datalog4.variable)("a")),
+      (0, import_datalog4.lit)("refersToParam", (0, import_datalog4.variable)("o"), (0, import_datalog4.variable)("p"))
+    ]
+  ),
+  // A parameter that defaults to the environment, for the callers that
+  // pass nothing. `loadConfig(env = process.env)` is written that way
+  // so that most of the program never mentions the environment at all.
+  (0, import_datalog4.rule)(
+    "environmentValue",
+    [(0, import_datalog4.variable)("w"), (0, import_datalog4.variable)("o")],
+    [
+      (0, import_datalog4.lit)("environmentValue", (0, import_datalog4.variable)("w"), (0, import_datalog4.variable)("d")),
+      (0, import_datalog4.lit)("paramDefault", (0, import_datalog4.variable)("p"), (0, import_datalog4.variable)("d")),
+      (0, import_datalog4.lit)("refersToParam", (0, import_datalog4.variable)("o"), (0, import_datalog4.variable)("p"))
+    ]
+  ),
+  // Which environment object a keyed read takes its entry from. The
+  // object comes first because a project writes a handful of those and
+  // thousands of keyed reads, and the join starts at the small end.
+  (0, import_datalog4.rule)(
+    "environmentRead",
+    [(0, import_datalog4.variable)("w"), (0, import_datalog4.variable)("site"), (0, import_datalog4.variable)("x")],
+    [
+      (0, import_datalog4.lit)("environmentValue", (0, import_datalog4.variable)("w"), (0, import_datalog4.variable)("o")),
+      (0, import_datalog4.lit)("readsKeyed", (0, import_datalog4.variable)("site"), (0, import_datalog4.variable)("o"), (0, import_datalog4.variable)("x"))
+    ]
+  ),
+  (0, import_datalog4.rule)(
+    "readsEnvNamed",
+    [(0, import_datalog4.variable)("site"), (0, import_datalog4.variable)("x")],
+    [(0, import_datalog4.lit)("environmentRead", (0, import_datalog4.variable)("w"), (0, import_datalog4.variable)("site"), (0, import_datalog4.variable)("x"))]
+  ),
   // A parameter whose value is an environment variable's name: a read
   // site takes its name from it, or it is handed on to a parameter that
   // does. Asked from the site, so the recursion runs callee to caller.
@@ -2176,10 +2235,25 @@ var STATED_RULES = [
       (0, import_datalog4.lit)("call", (0, import_datalog4.variable)("r"), (0, import_datalog4.variable)("c"))
     ]
   ),
-  // The expressions that refer to an object literal by binding alone: the
+  // A name bound to a factory's result, called: `const get =
+  // makeReader(env)` then `get(name)`. Written from the factory's call so
+  // the walk starts where `callsFunction` already has an answer.
+  (0, import_datalog4.rule)(
+    "callsFunction",
+    [(0, import_datalog4.variable)("r"), (0, import_datalog4.variable)("f")],
+    [
+      (0, import_datalog4.lit)("returnsValue", (0, import_datalog4.variable)("g"), (0, import_datalog4.variable)("f")),
+      (0, import_datalog4.lit)("callsFunction", (0, import_datalog4.variable)("r0"), (0, import_datalog4.variable)("g")),
+      (0, import_datalog4.lit)("callsNamed", (0, import_datalog4.variable)("r"), (0, import_datalog4.variable)("r0"))
+    ]
+  ),
+  // The expressions that refer to an object by binding alone: the
   // declaration written as it, a reference or import of that, and a
   // fallback over any of those. Asked from the object, so it visits only them.
   (0, import_datalog4.rule)("refersToObject", [(0, import_datalog4.variable)("obj"), (0, import_datalog4.variable)("obj")], [(0, import_datalog4.lit)("objectValue", (0, import_datalog4.variable)("obj"))]),
+  // The process environment is an object nothing declares, so a pack
+  // saying which expression spells it is the only way in.
+  (0, import_datalog4.rule)("refersToObject", [(0, import_datalog4.variable)("w"), (0, import_datalog4.variable)("w")], [(0, import_datalog4.lit)("environmentObject", (0, import_datalog4.variable)("w"))]),
   (0, import_datalog4.rule)(
     "refersToObject",
     [(0, import_datalog4.variable)("x"), (0, import_datalog4.variable)("obj")],
@@ -2569,12 +2643,33 @@ var RESOLUTION_QUESTIONS = [
     [(0, import_datalog4.variable)("f"), (0, import_datalog4.variable)("c")],
     [(0, import_datalog4.lit)("wanted", (0, import_datalog4.variable)("f")), (0, import_datalog4.lit)("returnsCall", (0, import_datalog4.variable)("f"), (0, import_datalog4.variable)("c"))]
   ),
-  // Seeded with the read sites, a handful per project, so one question
-  // gives every parameter a reader at a call could meet.
+  // Seeded with the expressions that spell the environment, a handful
+  // per project. The reads cannot be the seed: one written through a
+  // parameter is nowhere a scan of the source looks.
   (0, import_datalog4.rule)(
     "wantedParamNamesEnv",
     [(0, import_datalog4.variable)("p"), (0, import_datalog4.variable)("site")],
-    [(0, import_datalog4.lit)("wantedEnvSite", (0, import_datalog4.variable)("site")), (0, import_datalog4.lit)("paramNamesEnv", (0, import_datalog4.variable)("p"), (0, import_datalog4.variable)("site"))]
+    [
+      (0, import_datalog4.lit)("wantedEnvObject", (0, import_datalog4.variable)("w")),
+      (0, import_datalog4.lit)("environmentRead", (0, import_datalog4.variable)("w"), (0, import_datalog4.variable)("site"), (0, import_datalog4.variable)("x")),
+      (0, import_datalog4.lit)("paramNamesEnv", (0, import_datalog4.variable)("p"), (0, import_datalog4.variable)("site"))
+    ]
+  ),
+  // The same relation asked from one expression. Seeding from the
+  // objects instead would settle it for every expression in the
+  // project, and a caller holding an argument wants only that one.
+  (0, import_datalog4.rule)(
+    "wantedEnvironmentValue",
+    [(0, import_datalog4.variable)("o"), (0, import_datalog4.variable)("w")],
+    [(0, import_datalog4.lit)("wanted", (0, import_datalog4.variable)("o")), (0, import_datalog4.lit)("environmentValue", (0, import_datalog4.variable)("w"), (0, import_datalog4.variable)("o"))]
+  ),
+  // Whether an expression is a parameter under another name, for a
+  // caller deciding whether going and reading that parameter's callers
+  // could change the answer it already has.
+  (0, import_datalog4.rule)(
+    "wantedRefersToParam",
+    [(0, import_datalog4.variable)("o"), (0, import_datalog4.variable)("p")],
+    [(0, import_datalog4.lit)("wanted", (0, import_datalog4.variable)("o")), (0, import_datalog4.lit)("refersToParam", (0, import_datalog4.variable)("o"), (0, import_datalog4.variable)("p"))]
   ),
   (0, import_datalog4.rule)(
     "wantedComesFrom",
@@ -2792,6 +2887,19 @@ var RESOLUTION_QUESTIONS = [
     [(0, import_datalog4.variable)("c"), (0, import_datalog4.variable)("n")],
     [(0, import_datalog4.lit)("ancestryChain", (0, import_datalog4.variable)("c"), (0, import_datalog4.variable)("b")), (0, import_datalog4.lit)("declaresName", (0, import_datalog4.variable)("b"), (0, import_datalog4.variable)("n"))]
   ),
+  // The method behind each callback the chain registers, by the event
+  // that runs it. A base registering one reaches every class below it,
+  // and the method may be declared anywhere along the same chain.
+  (0, import_datalog4.rule)(
+    "wantedCallbackMethod",
+    [(0, import_datalog4.variable)("c"), (0, import_datalog4.variable)("event"), (0, import_datalog4.variable)("n"), (0, import_datalog4.variable)("held")],
+    [
+      (0, import_datalog4.lit)("ancestryChain", (0, import_datalog4.variable)("c"), (0, import_datalog4.variable)("b")),
+      (0, import_datalog4.lit)("classCallback", (0, import_datalog4.variable)("b"), (0, import_datalog4.variable)("event"), (0, import_datalog4.variable)("n")),
+      (0, import_datalog4.lit)("ancestryChain", (0, import_datalog4.variable)("c"), (0, import_datalog4.variable)("b2")),
+      (0, import_datalog4.lit)("holdsProperty", (0, import_datalog4.variable)("b2"), (0, import_datalog4.variable)("n"), (0, import_datalog4.variable)("held"))
+    ]
+  ),
   (0, import_datalog4.rule)("anchorChain", [(0, import_datalog4.variable)("x"), (0, import_datalog4.variable)("x")], [(0, import_datalog4.lit)("wantedAnchor", (0, import_datalog4.variable)("x"))]),
   (0, import_datalog4.rule)(
     "anchorChain",

package/dist/index.js

@@ -13,7 +13,7 @@ var ASKING_RELATIONS = [
   "wanted",
   "wantedUnder",
   "wantedSites",
-  "wantedEnvSite",
+  "wantedEnvObject",
   "wantedOrigin",
   "wantedCallOrigin",
   "wantedExportsOf",
@@ -1053,6 +1053,16 @@ function answersByKey(rows, placeholders = NO_PLACEHOLDERS) {
   }
   return answers;
 }
+function answersFor2(db, relation, key) {
+  const rows = db.lookup(relation, 0, key);
+  if (rows.length === 0) {
+    return [];
+  }
+  const placeholders = new Set(
+    rows.map((row) => String(row[1])).filter((answer) => db.has("placeholderValue", [answer]))
+  );
+  return answersByKey(rows, placeholders).get(key) ?? [];
+}
 function singleAnswers(rows, placeholders = NO_PLACEHOLDERS) {
   const settled = /* @__PURE__ */ new Map();
   for (const [key, answers] of answersByKey(rows, placeholders)) {
@@ -1144,38 +1154,42 @@ function writtenValuesByKey(db, keys, ask, relation = WRITTEN_AS) {
   return one;
 }
 function settledByKey(db, keys, ask, relation) {
-  const placeholders = placeholderValues(db);
-  const byKey = answersByKey(db.facts(relation), placeholders);
-  const direct = new Map(keys.map((key) => [key, byKey.get(key) ?? []]));
-  const calls = new Set(db.facts("call").map((row) => String(row[0])));
-  const throughCalls = [...direct.values()].flat().filter((answer) => calls.has(answer));
+  const direct = new Map(
+    keys.map((key) => [key, answersFor2(db, relation, key)])
+  );
+  const throughCalls = [...direct.values()].flat().filter((answer) => isCall(db, answer));
   if (throughCalls.length === 0) {
     return direct;
   }
   ask(throughCalls);
-  const deeper = singleAnswers(db.facts(relation), placeholders);
   return new Map(
     [...direct].map(([key, answers]) => [
       key,
-      collapseCalls(answers, calls, deeper)
+      collapseCalls(db, relation, answers)
     ])
   );
 }
-function collapseCalls(direct, calls, deeper) {
+function isCall(db, key) {
+  return db.lookup("call", 0, key).length > 0;
+}
+function collapseCalls(db, relation, direct) {
   return [
     ...new Set(
       direct.map(
-        (answer) => calls.has(answer) ? deeper.get(answer) ?? answer : answer
+        (answer) => isCall(db, answer) ? behindCall(db, relation, answer) : answer
       )
     )
   ];
 }
+function behindCall(db, relation, call) {
+  const answers = answersFor2(db, relation, call);
+  return answers.length === 1 ? answers[0] : call;
+}
 function writesLeft(db, key) {
-  const unstated = db.facts("writesUnstated").some((row) => String(row[0]) === key);
-  if (unstated) {
+  if (db.has("writesUnstated", [key])) {
     return [];
   }
-  const candidates = answersByKey(db.facts("mayHold"), placeholderValues(db)).get(key) ?? [];
+  const candidates = answersFor2(db, "mayHold", key);
   return candidates.length > 1 ? candidates : [];
 }
 
@@ -1946,6 +1960,51 @@ var STATED_RULES = [
     [v("x"), v("p")],
     [lit("refersToParam", v("y"), v("p")), lit("binds", v("x"), v("y"))]
   ),
+  // An expression whose value is the environment object w: the way a
+  // pack spells it, a name declared as that, or a parameter a caller
+  // handed one of those to, however many calls deep.
+  rule(
+    "environmentValue",
+    [v("w"), v("o")],
+    [lit("environmentObject", v("w")), lit("refersToObject", v("o"), v("w"))]
+  ),
+  rule(
+    "environmentValue",
+    [v("w"), v("o")],
+    [
+      lit("environmentValue", v("w"), v("a")),
+      lit("passesArgument", v("r"), v("p"), v("a")),
+      lit("refersToParam", v("o"), v("p"))
+    ]
+  ),
+  // A parameter that defaults to the environment, for the callers that
+  // pass nothing. `loadConfig(env = process.env)` is written that way
+  // so that most of the program never mentions the environment at all.
+  rule(
+    "environmentValue",
+    [v("w"), v("o")],
+    [
+      lit("environmentValue", v("w"), v("d")),
+      lit("paramDefault", v("p"), v("d")),
+      lit("refersToParam", v("o"), v("p"))
+    ]
+  ),
+  // Which environment object a keyed read takes its entry from. The
+  // object comes first because a project writes a handful of those and
+  // thousands of keyed reads, and the join starts at the small end.
+  rule(
+    "environmentRead",
+    [v("w"), v("site"), v("x")],
+    [
+      lit("environmentValue", v("w"), v("o")),
+      lit("readsKeyed", v("site"), v("o"), v("x"))
+    ]
+  ),
+  rule(
+    "readsEnvNamed",
+    [v("site"), v("x")],
+    [lit("environmentRead", v("w"), v("site"), v("x"))]
+  ),
   // A parameter whose value is an environment variable's name: a read
   // site takes its name from it, or it is handed on to a parameter that
   // does. Asked from the site, so the recursion runs callee to caller.
@@ -2109,10 +2168,25 @@ var STATED_RULES = [
       lit("call", v("r"), v("c"))
     ]
   ),
-  // The expressions that refer to an object literal by binding alone: the
+  // A name bound to a factory's result, called: `const get =
+  // makeReader(env)` then `get(name)`. Written from the factory's call so
+  // the walk starts where `callsFunction` already has an answer.
+  rule(
+    "callsFunction",
+    [v("r"), v("f")],
+    [
+      lit("returnsValue", v("g"), v("f")),
+      lit("callsFunction", v("r0"), v("g")),
+      lit("callsNamed", v("r"), v("r0"))
+    ]
+  ),
+  // The expressions that refer to an object by binding alone: the
   // declaration written as it, a reference or import of that, and a
   // fallback over any of those. Asked from the object, so it visits only them.
   rule("refersToObject", [v("obj"), v("obj")], [lit("objectValue", v("obj"))]),
+  // The process environment is an object nothing declares, so a pack
+  // saying which expression spells it is the only way in.
+  rule("refersToObject", [v("w"), v("w")], [lit("environmentObject", v("w"))]),
   rule(
     "refersToObject",
     [v("x"), v("obj")],
@@ -2502,12 +2576,33 @@ var RESOLUTION_QUESTIONS = [
     [v("f"), v("c")],
     [lit("wanted", v("f")), lit("returnsCall", v("f"), v("c"))]
   ),
-  // Seeded with the read sites, a handful per project, so one question
-  // gives every parameter a reader at a call could meet.
+  // Seeded with the expressions that spell the environment, a handful
+  // per project. The reads cannot be the seed: one written through a
+  // parameter is nowhere a scan of the source looks.
   rule(
     "wantedParamNamesEnv",
     [v("p"), v("site")],
-    [lit("wantedEnvSite", v("site")), lit("paramNamesEnv", v("p"), v("site"))]
+    [
+      lit("wantedEnvObject", v("w")),
+      lit("environmentRead", v("w"), v("site"), v("x")),
+      lit("paramNamesEnv", v("p"), v("site"))
+    ]
+  ),
+  // The same relation asked from one expression. Seeding from the
+  // objects instead would settle it for every expression in the
+  // project, and a caller holding an argument wants only that one.
+  rule(
+    "wantedEnvironmentValue",
+    [v("o"), v("w")],
+    [lit("wanted", v("o")), lit("environmentValue", v("w"), v("o"))]
+  ),
+  // Whether an expression is a parameter under another name, for a
+  // caller deciding whether going and reading that parameter's callers
+  // could change the answer it already has.
+  rule(
+    "wantedRefersToParam",
+    [v("o"), v("p")],
+    [lit("wanted", v("o")), lit("refersToParam", v("o"), v("p"))]
   ),
   rule(
     "wantedComesFrom",
@@ -2725,6 +2820,19 @@ var RESOLUTION_QUESTIONS = [
     [v("c"), v("n")],
     [lit("ancestryChain", v("c"), v("b")), lit("declaresName", v("b"), v("n"))]
   ),
+  // The method behind each callback the chain registers, by the event
+  // that runs it. A base registering one reaches every class below it,
+  // and the method may be declared anywhere along the same chain.
+  rule(
+    "wantedCallbackMethod",
+    [v("c"), v("event"), v("n"), v("held")],
+    [
+      lit("ancestryChain", v("c"), v("b")),
+      lit("classCallback", v("b"), v("event"), v("n")),
+      lit("ancestryChain", v("c"), v("b2")),
+      lit("holdsProperty", v("b2"), v("n"), v("held"))
+    ]
+  ),
   rule("anchorChain", [v("x"), v("x")], [lit("wantedAnchor", v("x"))]),
   rule(
     "anchorChain",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/resolution",
-  "version": "0.32.0",
+  "version": "0.33.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.32.0"
+    "@suss/datalog": "0.33.0"
   }
 }