@suss/resolution 0.8.0 → 0.10.0

package/README.md

@@ -57,14 +57,42 @@ demand nothing generates.
 
 Node identity is the adapter's business. The rules only join on it.
 
+## One relation of steps
+
+Every construct states its hops once, in one relation:
+
+```
+stepsTo(x, y, kind)         following x leads to y in one hop
+reaches(x, z, kind)         the closure of those hops
+```
+
+A value step goes to the value x is written as: a name to its
+declaration, an import to what the module exports, a parameter to what a
+call passes it, a property read to what the object contains under that
+name, a construction to the class, a transparent wrapper to the argument
+it wraps. A result step goes the other way, from a call to what the
+function it invokes returns. A walk counts as a result walk once it has
+run a call anywhere along it, which is what keeps a factory call out of
+the answers that stop at a value.
+
+A language with a hop of its own states it as a step too. JavaScript's
+`.bind` and Ruby's `Const.new` are each one rule, and every question
+below picks them up without being told.
+
+Each question is that one closure with its own stopping condition. So
+adding a construct is one step and every question gets it, and adding a
+question is a stopping condition and no steps at all.
+
 ## What comes out
 
 ```
 comesTo(x, z)               following x arrives at the value z
 resolves(x, z)              comesTo narrowed to functions
+givesBack(x, z)             following x arrives at a call that returns z
 isWrittenAs(x, z)           x is written as the expression z
 comesFrom(x, m, n)          following x arrives at m's export n
 callsInto(f, m, n)          calling f ends up calling m's n
+paramAt(r, p, z)            the call r puts z in the parameter p
 ```
 
 `resolves` is the question most callers ask. `comesTo` is the one
@@ -72,6 +100,21 @@ underneath it, and it can come back with an object, because a chain has
 to pass through objects for `routes.list` to reach whatever `list`
 contains.
 
+`givesBack` is the other direction of function application. `comesTo`
+says what a value comes down to, and it stops at a call on purpose: a
+factory call is usually the wrapper itself, so resolving it to the
+function it returned would fight the unwrapping answer. That leaves
+nobody able to ask what a call returned, which is the whole question
+when a factory builds a dependency. `givesBack` asks it, over the same
+steps and with the same stopping condition, of the walks that ran a
+call.
+
+Both directions run at once without interfering, because they answer
+different questions about the same call. `const dao = makeDao()` comes
+to nothing and gives back the class `makeDao` constructed, so
+`dao.findByCustomer` finds the method that class declares while
+`withAuth(handler)` still comes to `handler`.
+
 `isWrittenAs` follows the same names to the expression a value is
 written as, whatever kind of expression that turns out to be. A GraphQL
 document is neither a function nor an object, so `comesTo` never
@@ -80,8 +123,14 @@ reaches one.
 `comesFrom` covers the direction `comesTo` cannot. Every `comesTo` chain
 ends at something written out in the source suss is reading, so a name
 for a library's own function ends nowhere, because the library's body is
-not here. `comesFrom` follows the same aliases, imports and barrels, and
-comes back with the module plus the name that module exports.
+not here. `comesFrom` walks the same steps and stops at the import
+instead, so it comes back with the module plus the name that module
+exports.
+
+`paramAt` is the one question that keeps the call it went through.
+`comesTo` merges call sites, so a function called from two places leaves
+its parameter with two values and a caller wanting one gets nothing.
+`paramAt` says which call put which value there.
 
 `callsInto` puts that together with the calls a function makes. A
 project writes its own decorator that calls `Resolver()` and applies
@@ -91,19 +140,24 @@ normal rather than ambiguous, because a wrapper that combines two
 library decorators applies both of them, so a caller asks whether the
 one it cares about is among them.
 
-One relation exists for the rules' own use rather than for callers:
+Two relations exist for the rules' own use rather than for callers:
 
 ```
 objectOf(x, obj)            x stands for the object literal obj
+invokes(r, f)               the call r runs the function f
 ```
 
 An object arrives two ways, through a name or as what a factory call
-returns. `objectOf` gives that step a name, so the rule for
-`routes.list` and the rule for `make(body).handle` are the same rule. A
-factory call gets an `objectOf` answer without getting a `comesTo`
-answer, because a factory call is usually the wrapper itself, and
-answering with the function it returns would fight the unwrapping
-answer.
+gives back. `objectOf` gives that step a name, so the rule for
+`routes.list` and the rule for `make(body).handle` are the same rule.
+This is where the two directions meet: a factory call gets an
+`objectOf` answer without getting a `comesTo` answer.
+
+`invokes` is the callee half of `givesBack`, kept apart so the case
+where the callee is itself a call, `daoBuilder()()`, is one rule rather
+than a copy of every other. It differs from `callsFunction`, which
+starts from the function because a caller asking for call sites has the
+function in hand.
 
 ## Why rules and not a walker
 
@@ -119,6 +173,15 @@ resolved 11 handlers and missed most of what the template declared. The
 fix was one condition in fact extraction, and the existing rules found
 the rest without any change.
 
+## Changing a rule
+
+Every rule here composes with every other one, so a change meant for one
+construct lands on chains nobody had in mind. `@suss/resolution-fuzz`
+generates four thousand fact bases, runs these rules over each, and
+compares what came out against a committed baseline, which is what turns
+a change into a diff a reviewer reads. Run `npm run resolution:baseline`
+to accept one, and commit the rewritten file with the rule.
+
 ## What is not modelled
 
 **A handler passed as one property of a config.** `make({ body:

package/dist/index.cjs

@@ -24,6 +24,8 @@ __export(index_exports, {
   FACT_CONTRACT_CASES: () => FACT_CONTRACT_CASES,
   RESOLUTION_QUESTIONS: () => RESOLUTION_QUESTIONS,
   RESOLUTION_RULES: () => RESOLUTION_RULES,
+  RESULT_STEP: () => RESULT_STEP,
+  VALUE_STEP: () => VALUE_STEP,
   checkFactContract: () => checkFactContract
 });
 module.exports = __toCommonJS(index_exports);
@@ -202,35 +204,202 @@ function checkFactContract(sources, emit, options = {}) {
 
 // src/index.ts
 var import_datalog = require("@suss/datalog");
+var VALUE_STEP = (0, import_datalog.constant)("value");
+var RESULT_STEP = (0, import_datalog.constant)("result");
 var RESOLUTION_RULES = [
-  // A value comes to itself; every chain ends at something written out
-  // in source, a function or an object.
+  // Aliasing: const x = y, or an identifier referencing a declaration.
+  // A language with a hop of its own, like JavaScript's `.bind`, states
+  // it as a step too, or every question but `comesTo` misses it.
+  (0, import_datalog.rule)("stepsTo", [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("y"), VALUE_STEP], [(0, import_datalog.lit)("binds", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y"))]),
+  // A name written more than once has the value the last write left
+  // there. The adapter works out which write that is and stays quiet
+  // when control flow decides, so such a name steps nowhere at all.
+  (0, import_datalog.rule)(
+    "stepsTo",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("y"), VALUE_STEP],
+    [(0, import_datalog.lit)("endsHolding", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y"))]
+  ),
+  // An import steps to what the module exports under that name.
+  (0, import_datalog.rule)(
+    "stepsTo",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("value"), VALUE_STEP],
+    [
+      (0, import_datalog.lit)("imports", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")),
+      (0, import_datalog.lit)("moduleExport", (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("value"))
+    ]
+  ),
+  // A parameter steps to what a call passes it. A function called from
+  // several places leaves its parameter with more than one value, and a
+  // caller that needs those apart asks `paramAt`.
+  (0, import_datalog.rule)(
+    "stepsTo",
+    [(0, import_datalog.variable)("p"), (0, import_datalog.variable)("a"), VALUE_STEP],
+    [(0, import_datalog.lit)("passesArgument", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("p"), (0, import_datalog.variable)("a"))]
+  ),
+  // Reading a property steps to what the object contains under that
+  // name, whichever way the object arrived: `routes.list` off a name,
+  // or `make(body).handle` off a call.
+  (0, import_datalog.rule)(
+    "stepsTo",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("held"), VALUE_STEP],
+    [
+      (0, import_datalog.lit)("readsProperty", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("o"), (0, import_datalog.variable)("n")),
+      (0, import_datalog.lit)("objectOf", (0, import_datalog.variable)("o"), (0, import_datalog.variable)("obj")),
+      (0, import_datalog.lit)("contains", (0, import_datalog.variable)("obj"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("held"))
+    ]
+  ),
+  // Calling a class makes one of it, so the call steps to the class and
+  // a method read off the result is the one the class declares. The
+  // caveat below is about a factory function, and a class is not one.
+  (0, import_datalog.rule)(
+    "stepsTo",
+    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("cls"), VALUE_STEP],
+    [
+      (0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c")),
+      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("cls")),
+      (0, import_datalog.lit)("objectValue", (0, import_datalog.variable)("cls"))
+    ]
+  ),
+  // Wrapper transparency, derived: calling a factory that returns a
+  // function which calls its parameter k steps to argument k.
+  (0, import_datalog.rule)(
+    "stepsTo",
+    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("a"), VALUE_STEP],
+    [
+      (0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c")),
+      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("f")),
+      (0, import_datalog.lit)("unwraps", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("k")),
+      (0, import_datalog.lit)("callArg", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("k"), (0, import_datalog.variable)("a"))
+    ]
+  ),
+  // Wrapper transparency, declared: a pack says this callee wraps
+  // argument k. The callee has to come from the library the pack said,
+  // so a local object spelled the same way is not mistaken for it.
+  (0, import_datalog.rule)(
+    "stepsTo",
+    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("a"), VALUE_STEP],
+    [
+      (0, import_datalog.lit)("calleeName", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("n")),
+      (0, import_datalog.lit)("unwrapsByName", (0, import_datalog.variable)("n"), (0, import_datalog.variable)("k")),
+      (0, import_datalog.lit)("wrapperModule", (0, import_datalog.variable)("n"), (0, import_datalog.variable)("m")),
+      (0, import_datalog.lit)("calleeOrigin", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("m")),
+      (0, import_datalog.lit)("callArg", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("k"), (0, import_datalog.variable)("a"))
+    ]
+  ),
+  // The one step that runs a function forwards: a call steps to what
+  // the function it invokes returns.
+  (0, import_datalog.rule)(
+    "stepsTo",
+    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("ret"), RESULT_STEP],
+    [(0, import_datalog.lit)("invokes", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("f")), (0, import_datalog.lit)("returnsValue", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("ret"))]
+  ),
+  // 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.
+  (0, import_datalog.rule)(
+    "reaches",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"), (0, import_datalog.variable)("kind")],
+    [(0, import_datalog.lit)("stepsTo", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"), (0, import_datalog.variable)("kind"))]
+  ),
+  (0, import_datalog.rule)(
+    "reaches",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"), (0, import_datalog.variable)("kind")],
+    [
+      (0, import_datalog.lit)("stepsTo", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y"), VALUE_STEP),
+      (0, import_datalog.lit)("reaches", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("z"), (0, import_datalog.variable)("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
+  // demand-driven run then derives both to answer either.
+  (0, import_datalog.rule)(
+    "reaches",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"), RESULT_STEP],
+    [
+      (0, import_datalog.lit)("stepsTo", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y"), RESULT_STEP),
+      (0, import_datalog.lit)("reaches", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("z"), VALUE_STEP)
+    ]
+  ),
+  (0, import_datalog.rule)(
+    "reaches",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"), RESULT_STEP],
+    [
+      (0, import_datalog.lit)("stepsTo", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y"), RESULT_STEP),
+      (0, import_datalog.lit)("reaches", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("z"), RESULT_STEP)
+    ]
+  ),
+  // What a value comes down to: the walk that never ran a call, stopped
+  // at a function or an object. Something already written out comes to
+  // itself, and every other walk ends at one of those.
   (0, import_datalog.rule)("comesTo", [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("x")], [(0, import_datalog.lit)("func", (0, import_datalog.variable)("x"))]),
   (0, import_datalog.rule)("comesTo", [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("x")], [(0, import_datalog.lit)("objectValue", (0, import_datalog.variable)("x"))]),
-  // Aliasing: const x = y, or an identifier referencing a declaration.
   (0, import_datalog.rule)(
     "comesTo",
     [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
-    [(0, import_datalog.lit)("binds", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y")), (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("z"))]
+    [(0, import_datalog.lit)("reaches", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"), VALUE_STEP), (0, import_datalog.lit)("func", (0, import_datalog.variable)("z"))]
   ),
-  // A name written more than once has the value the last write left
-  // there, and `binds` says nothing about it. The adapter works out
-  // which write that is, in its own language's terms, and stays quiet
-  // when control flow decides. A name it stays quiet about comes to no
-  // value, which is the answer.
   (0, import_datalog.rule)(
     "comesTo",
     [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
-    [(0, import_datalog.lit)("endsHolding", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y")), (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("z"))]
+    [(0, import_datalog.lit)("reaches", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"), VALUE_STEP), (0, import_datalog.lit)("objectValue", (0, import_datalog.variable)("z"))]
   ),
-  // An import comes to what the module exports under that name.
+  // The same stopping condition, for the walk that ran a call. A call
+  // gets no `comesTo` answer on purpose: coming back with what a
+  // factory returned would fight the unwrapping answer.
   (0, import_datalog.rule)(
-    "comesTo",
+    "givesBack",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
+    [(0, import_datalog.lit)("reaches", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"), RESULT_STEP), (0, import_datalog.lit)("func", (0, import_datalog.variable)("z"))]
+  ),
+  (0, import_datalog.rule)(
+    "givesBack",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
+    [(0, import_datalog.lit)("reaches", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"), RESULT_STEP), (0, import_datalog.lit)("objectValue", (0, import_datalog.variable)("z"))]
+  ),
+  // Following a value to the expression it is written as, whatever kind
+  // that is. A GraphQL document is neither a function nor an object, so
+  // `comesTo` never reaches one.
+  (0, import_datalog.rule)("isWrittenAs", [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("x")], [(0, import_datalog.lit)("writtenValue", (0, import_datalog.variable)("x"))]),
+  (0, import_datalog.rule)("isWrittenAs", [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("x")], [(0, import_datalog.lit)("objectValue", (0, import_datalog.variable)("x"))]),
+  (0, import_datalog.rule)(
+    "isWrittenAs",
     [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
+    [(0, import_datalog.lit)("reaches", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"), VALUE_STEP), (0, import_datalog.lit)("writtenValue", (0, import_datalog.variable)("z"))]
+  ),
+  (0, import_datalog.rule)(
+    "isWrittenAs",
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
+    [(0, import_datalog.lit)("reaches", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"), VALUE_STEP), (0, import_datalog.lit)("objectValue", (0, import_datalog.variable)("z"))]
+  ),
+  // What one call site put in a parameter, told apart from what the
+  // other callers passed.
+  (0, import_datalog.rule)(
+    "paramAt",
+    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("p"), (0, import_datalog.variable)("z")],
     [
-      (0, import_datalog.lit)("imports", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")),
-      (0, import_datalog.lit)("moduleExport", (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("value")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("value"), (0, import_datalog.variable)("z"))
+      (0, import_datalog.lit)("passesArgument", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("p"), (0, import_datalog.variable)("a")),
+      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("a"), (0, import_datalog.variable)("z"))
+    ]
+  ),
+  // An argument arriving at the parameter it is passed to, by position
+  // or by the name the caller wrote, keeping the call it went through
+  // so `paramAt` can tell two call sites apart.
+  (0, import_datalog.rule)(
+    "passesArgument",
+    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("p"), (0, import_datalog.variable)("a")],
+    [
+      (0, import_datalog.lit)("paramOf", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("k"), (0, import_datalog.variable)("p")),
+      (0, import_datalog.lit)("callsFunction", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("f")),
+      (0, import_datalog.lit)("callArg", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("k"), (0, import_datalog.variable)("a"))
+    ]
+  ),
+  (0, import_datalog.rule)(
+    "passesArgument",
+    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("p"), (0, import_datalog.variable)("a")],
+    [
+      (0, import_datalog.lit)("paramNamed", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("p")),
+      (0, import_datalog.lit)("callsFunction", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("f")),
+      (0, import_datalog.lit)("callKeywordArg", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("a"))
     ]
   ),
   // What a module exports: directly, or through re-export chains.
@@ -255,12 +424,22 @@ var RESOLUTION_RULES = [
       (0, import_datalog.lit)("moduleExport", (0, import_datalog.variable)("m2"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("value"))
     ]
   ),
-  // The object an expression refers to. A name arrives at one by
-  // following `comesTo` through aliases and imports. A factory call
-  // arrives at one through what the function it calls returns; the
-  // call itself is given no `comesTo`, since a factory call usually IS
-  // the wrapper and answering with the raw returned function would
-  // fight the unwraps answer.
+  // The function a call runs, written from the call's side because a
+  // caller asking what a call gives back has the call in hand.
+  (0, import_datalog.rule)(
+    "invokes",
+    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("f")],
+    [(0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c")), (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("f"))]
+  ),
+  // The callee is itself a call: `daoBuilder()()`.
+  (0, import_datalog.rule)(
+    "invokes",
+    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("f")],
+    [(0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c")), (0, import_datalog.lit)("givesBack", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("f"))]
+  ),
+  // The object an expression refers to: a name through `comesTo`, a
+  // factory call through what it gives back. Naming the step is what
+  // makes `routes.list` and `make(body).handle` one rule.
   (0, import_datalog.rule)(
     "objectOf",
     [(0, import_datalog.variable)("o"), (0, import_datalog.variable)("obj")],
@@ -268,14 +447,8 @@ var RESOLUTION_RULES = [
   ),
   (0, import_datalog.rule)(
     "objectOf",
-    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("obj")],
-    [
-      (0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("f")),
-      (0, import_datalog.lit)("returnsValue", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("ret")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("ret"), (0, import_datalog.variable)("obj")),
-      (0, import_datalog.lit)("objectValue", (0, import_datalog.variable)("obj"))
-    ]
+    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("obj")],
+    [(0, import_datalog.lit)("givesBack", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("obj")), (0, import_datalog.lit)("objectValue", (0, import_datalog.variable)("obj"))]
   ),
   // Which calls a function, found by the name the call is written as
   // rather than by resolving every callee in the project. A caller knows
@@ -308,42 +481,6 @@ var RESOLUTION_RULES = [
       (0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c"))
     ]
   ),
-  // A function whose return is itself a call arrives at the same object
-  // that call does, so a chain passing through two factories settles.
-  (0, import_datalog.rule)(
-    "objectOf",
-    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("obj")],
-    [
-      (0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("f")),
-      (0, import_datalog.lit)("returnsValue", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("ret")),
-      (0, import_datalog.lit)("objectOf", (0, import_datalog.variable)("ret"), (0, import_datalog.variable)("obj"))
-    ]
-  ),
-  // An argument reaches the parameter it is passed to, by position or
-  // by the name the caller wrote. A function called from several places
-  // leaves its parameter with more than one value, and the caller
-  // decides what to do about that.
-  (0, import_datalog.rule)(
-    "comesTo",
-    [(0, import_datalog.variable)("p"), (0, import_datalog.variable)("z")],
-    [
-      (0, import_datalog.lit)("paramOf", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("k"), (0, import_datalog.variable)("p")),
-      (0, import_datalog.lit)("callsFunction", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("f")),
-      (0, import_datalog.lit)("callArg", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("k"), (0, import_datalog.variable)("a")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("a"), (0, import_datalog.variable)("z"))
-    ]
-  ),
-  (0, import_datalog.rule)(
-    "comesTo",
-    [(0, import_datalog.variable)("p"), (0, import_datalog.variable)("z")],
-    [
-      (0, import_datalog.lit)("paramNamed", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("p")),
-      (0, import_datalog.lit)("callsFunction", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("f")),
-      (0, import_datalog.lit)("callKeywordArg", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("a")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("a"), (0, import_datalog.variable)("z"))
-    ]
-  ),
   // What an object contains, its base class included, so a method the base
   // declares is found on a subclass that never overrode it. A method both
   // declare gives two, and the caller decides. This is its own relation
@@ -363,33 +500,8 @@ var RESOLUTION_RULES = [
       (0, import_datalog.lit)("contains", (0, import_datalog.variable)("baseCls"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("held"))
     ]
   ),
-  // Calling a class makes one of it, and reading a method off the
-  // result finds the method the class declares. The caveat above is
-  // about a factory function, and a class is not one.
-  (0, import_datalog.rule)(
-    "comesTo",
-    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("cls")],
-    [
-      (0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("cls")),
-      (0, import_datalog.lit)("objectValue", (0, import_datalog.variable)("cls"))
-    ]
-  ),
-  // Reading a property comes to what the object holds under that name,
-  // whichever way the object arrived: `routes.list` off a name, or
-  // `make(body).handle` off a call.
-  (0, import_datalog.rule)(
-    "comesTo",
-    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
-    [
-      (0, import_datalog.lit)("readsProperty", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("o"), (0, import_datalog.variable)("n")),
-      (0, import_datalog.lit)("objectOf", (0, import_datalog.variable)("o"), (0, import_datalog.variable)("obj")),
-      (0, import_datalog.lit)("contains", (0, import_datalog.variable)("obj"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("held")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("held"), (0, import_datalog.variable)("z"))
-    ]
-  ),
-  // Wrapper transparency, derived: calling a factory that returns a
-  // function which calls its parameter k comes to argument k.
+  // Which function a factory returns, and which of its parameters that
+  // function calls: together they are what makes it a wrapper.
   (0, import_datalog.rule)(
     "returnsFunc",
     [(0, import_datalog.variable)("f"), (0, import_datalog.variable)("g")],
@@ -450,56 +562,20 @@ var RESOLUTION_RULES = [
       (0, import_datalog.lit)("paramOf", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("k"), (0, import_datalog.variable)("p"))
     ]
   ),
-  (0, import_datalog.rule)(
-    "comesTo",
-    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("h")],
-    [
-      (0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("f")),
-      (0, import_datalog.lit)("unwraps", (0, import_datalog.variable)("f"), (0, import_datalog.variable)("k")),
-      (0, import_datalog.lit)("callArg", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("k"), (0, import_datalog.variable)("a")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("a"), (0, import_datalog.variable)("h"))
-    ]
-  ),
-  // Wrapper transparency, declared: a pack says this callee wraps
-  // argument k, whatever its implementation looks like. The callee has
-  // to have been imported from the library the pack named, so a local
-  // object spelled the same way is not mistaken for it.
-  (0, import_datalog.rule)(
-    "comesTo",
-    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("h")],
-    [
-      (0, import_datalog.lit)("calleeName", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("n")),
-      (0, import_datalog.lit)("unwrapsByName", (0, import_datalog.variable)("n"), (0, import_datalog.variable)("k")),
-      (0, import_datalog.lit)("wrapperModule", (0, import_datalog.variable)("n"), (0, import_datalog.variable)("m")),
-      (0, import_datalog.lit)("calleeOrigin", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("m")),
-      (0, import_datalog.lit)("callArg", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("k"), (0, import_datalog.variable)("a")),
-      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("a"), (0, import_datalog.variable)("h"))
-    ]
-  ),
   // Where a name comes from, when what it refers to lives outside the
-  // source being read. `comesTo` ends at something written out, so it
-  // never reaches a library's own function, and a project's alias of a
-  // library name has no answer at all. This follows the same aliases
-  // and barrels in the other direction and answers with the module and
-  // the name that module exports.
+  // source being read. A walk ends at something written out in source,
+  // so it never reaches a library's own function.
   (0, import_datalog.rule)(
     "comesFrom",
     [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")],
     [(0, import_datalog.lit)("imports", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"))]
   ),
-  (0, import_datalog.rule)(
-    "comesFrom",
-    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")],
-    [(0, import_datalog.lit)("binds", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y")), (0, import_datalog.lit)("comesFrom", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"))]
-  ),
   (0, import_datalog.rule)(
     "comesFrom",
     [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")],
     [
-      (0, import_datalog.lit)("imports", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("m2"), (0, import_datalog.variable)("n2")),
-      (0, import_datalog.lit)("moduleExport", (0, import_datalog.variable)("m2"), (0, import_datalog.variable)("n2"), (0, import_datalog.variable)("value")),
-      (0, import_datalog.lit)("comesFrom", (0, import_datalog.variable)("value"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"))
+      (0, import_datalog.lit)("reaches", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y"), VALUE_STEP),
+      (0, import_datalog.lit)("imports", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"))
     ]
   ),
   // Calling f ends up calling the name n that module m exports. One hop
@@ -535,36 +611,6 @@ var RESOLUTION_RULES = [
     "resolves",
     [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
     [(0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")), (0, import_datalog.lit)("func", (0, import_datalog.variable)("z"))]
-  ),
-  // Following a name to the expression it is written as. A separate
-  // relation rather than a widening of `comesTo`, so a caller asking
-  // the older question never sees a new answer: a factory call already
-  // has an unwrapping answer, and letting it also answer with itself
-  // would make that pair ambiguous.
-  //
-  // The two seeds are the two ways an expression can be written out. An
-  // object literal is one of them, and it is the shape a generated
-  // GraphQL document takes.
-  (0, import_datalog.rule)("isWrittenAs", [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("x")], [(0, import_datalog.lit)("writtenValue", (0, import_datalog.variable)("x"))]),
-  (0, import_datalog.rule)("isWrittenAs", [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("x")], [(0, import_datalog.lit)("objectValue", (0, import_datalog.variable)("x"))]),
-  (0, import_datalog.rule)(
-    "isWrittenAs",
-    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
-    [(0, import_datalog.lit)("binds", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y")), (0, import_datalog.lit)("isWrittenAs", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("z"))]
-  ),
-  (0, import_datalog.rule)(
-    "isWrittenAs",
-    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
-    [(0, import_datalog.lit)("endsHolding", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("y")), (0, import_datalog.lit)("isWrittenAs", (0, import_datalog.variable)("y"), (0, import_datalog.variable)("z"))]
-  ),
-  (0, import_datalog.rule)(
-    "isWrittenAs",
-    [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
-    [
-      (0, import_datalog.lit)("imports", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")),
-      (0, import_datalog.lit)("moduleExport", (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("value")),
-      (0, import_datalog.lit)("isWrittenAs", (0, import_datalog.variable)("value"), (0, import_datalog.variable)("z"))
-    ]
   )
 ];
 var RESOLUTION_QUESTIONS = [
@@ -596,6 +642,13 @@ var RESOLUTION_QUESTIONS = [
     [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("z")],
     [(0, import_datalog.lit)("wanted", (0, import_datalog.variable)("x")), (0, import_datalog.lit)("objectOf", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"))]
   ),
+  // Keyed by the parameter, since that is what a caller has in hand
+  // when it wants the call sites told apart.
+  (0, import_datalog.rule)(
+    "wantedParamAt",
+    [(0, import_datalog.variable)("p"), (0, import_datalog.variable)("r"), (0, import_datalog.variable)("z")],
+    [(0, import_datalog.lit)("wanted", (0, import_datalog.variable)("p")), (0, import_datalog.lit)("paramAt", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("p"), (0, import_datalog.variable)("z"))]
+  ),
   (0, import_datalog.rule)(
     "wantedComesFrom",
     [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")],
@@ -620,5 +673,7 @@ var ANSWER_RELATIONS = [
   FACT_CONTRACT_CASES,
   RESOLUTION_QUESTIONS,
   RESOLUTION_RULES,
+  RESULT_STEP,
+  VALUE_STEP,
   checkFactContract
 });

package/dist/index.d.cts

@@ -36,9 +36,23 @@ declare function checkFactContract(sources: Readonly<Record<string, CaseFiles>>,
     problem: string;
 }[]>;
 
+/** A step to the value x is written as. */
+declare const VALUE_STEP: _suss_datalog.Term;
+/** A step to what running the call x is handed back. */
+declare const RESULT_STEP: _suss_datalog.Term;
 /**
  * The rules every language adapter shares. Concatenate a language's own
  * rules onto these before evaluating.
+ *
+ * Every construct states its hops once, as `stepsTo(x, y, kind)`, which
+ * says x leads to y. A value step goes to the value x is written as, and a
+ * result step runs the call x is and goes to what that call handed back.
+ * `reaches` is the closure of those steps, and a walk counts as a result
+ * walk once it has run a call anywhere along it.
+ *
+ * Each question is that one closure with its own stopping condition, so
+ * adding a construct is one step and every question gets it, and adding
+ * a question is a stopping condition and no steps at all.
  */
 declare const RESOLUTION_RULES: _suss_datalog.Rule[];
 /**
@@ -62,4 +76,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, FACT_CONTRACT_CASES, type FactsOf, RESOLUTION_QUESTIONS, RESOLUTION_RULES, checkFactContract };
+export { ANSWER_RELATIONS, type CaseFiles, type ContractCase, type ContractOptions, FACT_CONTRACT_CASES, type FactsOf, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, VALUE_STEP, checkFactContract };

package/dist/index.d.ts

@@ -36,9 +36,23 @@ declare function checkFactContract(sources: Readonly<Record<string, CaseFiles>>,
     problem: string;
 }[]>;
 
+/** A step to the value x is written as. */
+declare const VALUE_STEP: _suss_datalog.Term;
+/** A step to what running the call x is handed back. */
+declare const RESULT_STEP: _suss_datalog.Term;
 /**
  * The rules every language adapter shares. Concatenate a language's own
  * rules onto these before evaluating.
+ *
+ * Every construct states its hops once, as `stepsTo(x, y, kind)`, which
+ * says x leads to y. A value step goes to the value x is written as, and a
+ * result step runs the call x is and goes to what that call handed back.
+ * `reaches` is the closure of those steps, and a walk counts as a result
+ * walk once it has run a call anywhere along it.
+ *
+ * Each question is that one closure with its own stopping condition, so
+ * adding a construct is one step and every question gets it, and adding
+ * a question is a stopping condition and no steps at all.
  */
 declare const RESOLUTION_RULES: _suss_datalog.Rule[];
 /**
@@ -62,4 +76,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, FACT_CONTRACT_CASES, type FactsOf, RESOLUTION_QUESTIONS, RESOLUTION_RULES, checkFactContract };
+export { ANSWER_RELATIONS, type CaseFiles, type ContractCase, type ContractOptions, FACT_CONTRACT_CASES, type FactsOf, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, VALUE_STEP, checkFactContract };

package/dist/index.js

@@ -171,36 +171,203 @@ function checkFactContract(sources, emit, options = {}) {
 }
 
 // src/index.ts
-import { lit, rule, variable as v } from "@suss/datalog";
+import { constant, lit, rule, variable as v } from "@suss/datalog";
+var VALUE_STEP = constant("value");
+var RESULT_STEP = constant("result");
 var RESOLUTION_RULES = [
-  // A value comes to itself; every chain ends at something written out
-  // in source, a function or an object.
+  // Aliasing: const x = y, or an identifier referencing a declaration.
+  // A language with a hop of its own, like JavaScript's `.bind`, states
+  // it as a step too, or every question but `comesTo` misses it.
+  rule("stepsTo", [v("x"), v("y"), VALUE_STEP], [lit("binds", v("x"), v("y"))]),
+  // A name written more than once has the value the last write left
+  // there. The adapter works out which write that is and stays quiet
+  // when control flow decides, so such a name steps nowhere at all.
+  rule(
+    "stepsTo",
+    [v("x"), v("y"), VALUE_STEP],
+    [lit("endsHolding", v("x"), v("y"))]
+  ),
+  // An import steps to what the module exports under that name.
+  rule(
+    "stepsTo",
+    [v("x"), v("value"), VALUE_STEP],
+    [
+      lit("imports", v("x"), v("m"), v("n")),
+      lit("moduleExport", v("m"), v("n"), v("value"))
+    ]
+  ),
+  // A parameter steps to what a call passes it. A function called from
+  // several places leaves its parameter with more than one value, and a
+  // caller that needs those apart asks `paramAt`.
+  rule(
+    "stepsTo",
+    [v("p"), v("a"), VALUE_STEP],
+    [lit("passesArgument", v("r"), v("p"), v("a"))]
+  ),
+  // Reading a property steps to what the object contains under that
+  // name, whichever way the object arrived: `routes.list` off a name,
+  // or `make(body).handle` off a call.
+  rule(
+    "stepsTo",
+    [v("x"), v("held"), VALUE_STEP],
+    [
+      lit("readsProperty", v("x"), v("o"), v("n")),
+      lit("objectOf", v("o"), v("obj")),
+      lit("contains", v("obj"), v("n"), v("held"))
+    ]
+  ),
+  // Calling a class makes one of it, so the call steps to the class and
+  // a method read off the result is the one the class declares. The
+  // caveat below is about a factory function, and a class is not one.
+  rule(
+    "stepsTo",
+    [v("r"), v("cls"), VALUE_STEP],
+    [
+      lit("call", v("r"), v("c")),
+      lit("comesTo", v("c"), v("cls")),
+      lit("objectValue", v("cls"))
+    ]
+  ),
+  // Wrapper transparency, derived: calling a factory that returns a
+  // function which calls its parameter k steps to argument k.
+  rule(
+    "stepsTo",
+    [v("r"), v("a"), VALUE_STEP],
+    [
+      lit("call", v("r"), v("c")),
+      lit("comesTo", v("c"), v("f")),
+      lit("unwraps", v("f"), v("k")),
+      lit("callArg", v("r"), v("k"), v("a"))
+    ]
+  ),
+  // Wrapper transparency, declared: a pack says this callee wraps
+  // argument k. The callee has to come from the library the pack said,
+  // so a local object spelled the same way is not mistaken for it.
+  rule(
+    "stepsTo",
+    [v("r"), v("a"), VALUE_STEP],
+    [
+      lit("calleeName", v("r"), v("n")),
+      lit("unwrapsByName", v("n"), v("k")),
+      lit("wrapperModule", v("n"), v("m")),
+      lit("calleeOrigin", v("r"), v("m")),
+      lit("callArg", v("r"), v("k"), v("a"))
+    ]
+  ),
+  // The one step that runs a function forwards: a call steps to what
+  // the function it invokes returns.
+  rule(
+    "stepsTo",
+    [v("r"), v("ret"), RESULT_STEP],
+    [lit("invokes", v("r"), v("f")), lit("returnsValue", v("f"), v("ret"))]
+  ),
+  // 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.
+  rule(
+    "reaches",
+    [v("x"), v("z"), v("kind")],
+    [lit("stepsTo", v("x"), v("z"), v("kind"))]
+  ),
+  rule(
+    "reaches",
+    [v("x"), v("z"), v("kind")],
+    [
+      lit("stepsTo", v("x"), v("y"), VALUE_STEP),
+      lit("reaches", 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
+  // 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)
+    ]
+  ),
+  rule(
+    "reaches",
+    [v("x"), v("z"), RESULT_STEP],
+    [
+      lit("stepsTo", v("x"), v("y"), RESULT_STEP),
+      lit("reaches", v("y"), v("z"), RESULT_STEP)
+    ]
+  ),
+  // What a value comes down to: the walk that never ran a call, stopped
+  // at a function or an object. Something already written out comes to
+  // itself, and every other walk ends at one of those.
   rule("comesTo", [v("x"), v("x")], [lit("func", v("x"))]),
   rule("comesTo", [v("x"), v("x")], [lit("objectValue", v("x"))]),
-  // Aliasing: const x = y, or an identifier referencing a declaration.
   rule(
     "comesTo",
     [v("x"), v("z")],
-    [lit("binds", v("x"), v("y")), lit("comesTo", v("y"), v("z"))]
+    [lit("reaches", v("x"), v("z"), VALUE_STEP), lit("func", v("z"))]
   ),
-  // A name written more than once has the value the last write left
-  // there, and `binds` says nothing about it. The adapter works out
-  // which write that is, in its own language's terms, and stays quiet
-  // when control flow decides. A name it stays quiet about comes to no
-  // value, which is the answer.
   rule(
     "comesTo",
     [v("x"), v("z")],
-    [lit("endsHolding", v("x"), v("y")), lit("comesTo", v("y"), v("z"))]
+    [lit("reaches", v("x"), v("z"), VALUE_STEP), lit("objectValue", v("z"))]
   ),
-  // An import comes to what the module exports under that name.
+  // The same stopping condition, for the walk that ran a call. A call
+  // gets no `comesTo` answer on purpose: coming back with what a
+  // factory returned would fight the unwrapping answer.
   rule(
-    "comesTo",
+    "givesBack",
+    [v("x"), v("z")],
+    [lit("reaches", v("x"), v("z"), RESULT_STEP), lit("func", v("z"))]
+  ),
+  rule(
+    "givesBack",
+    [v("x"), v("z")],
+    [lit("reaches", v("x"), v("z"), RESULT_STEP), lit("objectValue", v("z"))]
+  ),
+  // Following a value to the expression it is written as, whatever kind
+  // that is. A GraphQL document is neither a function nor an object, so
+  // `comesTo` never reaches one.
+  rule("isWrittenAs", [v("x"), v("x")], [lit("writtenValue", v("x"))]),
+  rule("isWrittenAs", [v("x"), v("x")], [lit("objectValue", v("x"))]),
+  rule(
+    "isWrittenAs",
     [v("x"), v("z")],
+    [lit("reaches", v("x"), v("z"), VALUE_STEP), lit("writtenValue", v("z"))]
+  ),
+  rule(
+    "isWrittenAs",
+    [v("x"), v("z")],
+    [lit("reaches", v("x"), v("z"), VALUE_STEP), lit("objectValue", v("z"))]
+  ),
+  // What one call site put in a parameter, told apart from what the
+  // other callers passed.
+  rule(
+    "paramAt",
+    [v("r"), v("p"), v("z")],
     [
-      lit("imports", v("x"), v("m"), v("n")),
-      lit("moduleExport", v("m"), v("n"), v("value")),
-      lit("comesTo", v("value"), v("z"))
+      lit("passesArgument", v("r"), v("p"), v("a")),
+      lit("comesTo", v("a"), v("z"))
+    ]
+  ),
+  // An argument arriving at the parameter it is passed to, by position
+  // or by the name the caller wrote, keeping the call it went through
+  // so `paramAt` can tell two call sites apart.
+  rule(
+    "passesArgument",
+    [v("r"), v("p"), v("a")],
+    [
+      lit("paramOf", v("f"), v("k"), v("p")),
+      lit("callsFunction", v("r"), v("f")),
+      lit("callArg", v("r"), v("k"), v("a"))
+    ]
+  ),
+  rule(
+    "passesArgument",
+    [v("r"), v("p"), v("a")],
+    [
+      lit("paramNamed", v("f"), v("n"), v("p")),
+      lit("callsFunction", v("r"), v("f")),
+      lit("callKeywordArg", v("r"), v("n"), v("a"))
     ]
   ),
   // What a module exports: directly, or through re-export chains.
@@ -225,12 +392,22 @@ var RESOLUTION_RULES = [
       lit("moduleExport", v("m2"), v("n"), v("value"))
     ]
   ),
-  // The object an expression refers to. A name arrives at one by
-  // following `comesTo` through aliases and imports. A factory call
-  // arrives at one through what the function it calls returns; the
-  // call itself is given no `comesTo`, since a factory call usually IS
-  // the wrapper and answering with the raw returned function would
-  // fight the unwraps answer.
+  // The function a call runs, written from the call's side because a
+  // caller asking what a call gives back has the call in hand.
+  rule(
+    "invokes",
+    [v("r"), v("f")],
+    [lit("call", v("r"), v("c")), lit("comesTo", v("c"), v("f"))]
+  ),
+  // The callee is itself a call: `daoBuilder()()`.
+  rule(
+    "invokes",
+    [v("r"), v("f")],
+    [lit("call", v("r"), v("c")), lit("givesBack", v("c"), v("f"))]
+  ),
+  // The object an expression refers to: a name through `comesTo`, a
+  // factory call through what it gives back. Naming the step is what
+  // makes `routes.list` and `make(body).handle` one rule.
   rule(
     "objectOf",
     [v("o"), v("obj")],
@@ -238,14 +415,8 @@ var RESOLUTION_RULES = [
   ),
   rule(
     "objectOf",
-    [v("r"), v("obj")],
-    [
-      lit("call", v("r"), v("c")),
-      lit("comesTo", v("c"), v("f")),
-      lit("returnsValue", v("f"), v("ret")),
-      lit("comesTo", v("ret"), v("obj")),
-      lit("objectValue", v("obj"))
-    ]
+    [v("x"), v("obj")],
+    [lit("givesBack", v("x"), v("obj")), lit("objectValue", v("obj"))]
   ),
   // Which calls a function, found by the name the call is written as
   // rather than by resolving every callee in the project. A caller knows
@@ -278,42 +449,6 @@ var RESOLUTION_RULES = [
       lit("call", v("r"), v("c"))
     ]
   ),
-  // A function whose return is itself a call arrives at the same object
-  // that call does, so a chain passing through two factories settles.
-  rule(
-    "objectOf",
-    [v("r"), v("obj")],
-    [
-      lit("call", v("r"), v("c")),
-      lit("comesTo", v("c"), v("f")),
-      lit("returnsValue", v("f"), v("ret")),
-      lit("objectOf", v("ret"), v("obj"))
-    ]
-  ),
-  // An argument reaches the parameter it is passed to, by position or
-  // by the name the caller wrote. A function called from several places
-  // leaves its parameter with more than one value, and the caller
-  // decides what to do about that.
-  rule(
-    "comesTo",
-    [v("p"), v("z")],
-    [
-      lit("paramOf", v("f"), v("k"), v("p")),
-      lit("callsFunction", v("r"), v("f")),
-      lit("callArg", v("r"), v("k"), v("a")),
-      lit("comesTo", v("a"), v("z"))
-    ]
-  ),
-  rule(
-    "comesTo",
-    [v("p"), v("z")],
-    [
-      lit("paramNamed", v("f"), v("n"), v("p")),
-      lit("callsFunction", v("r"), v("f")),
-      lit("callKeywordArg", v("r"), v("n"), v("a")),
-      lit("comesTo", v("a"), v("z"))
-    ]
-  ),
   // What an object contains, its base class included, so a method the base
   // declares is found on a subclass that never overrode it. A method both
   // declare gives two, and the caller decides. This is its own relation
@@ -333,33 +468,8 @@ var RESOLUTION_RULES = [
       lit("contains", v("baseCls"), v("n"), v("held"))
     ]
   ),
-  // Calling a class makes one of it, and reading a method off the
-  // result finds the method the class declares. The caveat above is
-  // about a factory function, and a class is not one.
-  rule(
-    "comesTo",
-    [v("r"), v("cls")],
-    [
-      lit("call", v("r"), v("c")),
-      lit("comesTo", v("c"), v("cls")),
-      lit("objectValue", v("cls"))
-    ]
-  ),
-  // Reading a property comes to what the object holds under that name,
-  // whichever way the object arrived: `routes.list` off a name, or
-  // `make(body).handle` off a call.
-  rule(
-    "comesTo",
-    [v("x"), v("z")],
-    [
-      lit("readsProperty", v("x"), v("o"), v("n")),
-      lit("objectOf", v("o"), v("obj")),
-      lit("contains", v("obj"), v("n"), v("held")),
-      lit("comesTo", v("held"), v("z"))
-    ]
-  ),
-  // Wrapper transparency, derived: calling a factory that returns a
-  // function which calls its parameter k comes to argument k.
+  // Which function a factory returns, and which of its parameters that
+  // function calls: together they are what makes it a wrapper.
   rule(
     "returnsFunc",
     [v("f"), v("g")],
@@ -420,56 +530,20 @@ var RESOLUTION_RULES = [
       lit("paramOf", v("f"), v("k"), v("p"))
     ]
   ),
-  rule(
-    "comesTo",
-    [v("r"), v("h")],
-    [
-      lit("call", v("r"), v("c")),
-      lit("comesTo", v("c"), v("f")),
-      lit("unwraps", v("f"), v("k")),
-      lit("callArg", v("r"), v("k"), v("a")),
-      lit("comesTo", v("a"), v("h"))
-    ]
-  ),
-  // Wrapper transparency, declared: a pack says this callee wraps
-  // argument k, whatever its implementation looks like. The callee has
-  // to have been imported from the library the pack named, so a local
-  // object spelled the same way is not mistaken for it.
-  rule(
-    "comesTo",
-    [v("r"), v("h")],
-    [
-      lit("calleeName", v("r"), v("n")),
-      lit("unwrapsByName", v("n"), v("k")),
-      lit("wrapperModule", v("n"), v("m")),
-      lit("calleeOrigin", v("r"), v("m")),
-      lit("callArg", v("r"), v("k"), v("a")),
-      lit("comesTo", v("a"), v("h"))
-    ]
-  ),
   // Where a name comes from, when what it refers to lives outside the
-  // source being read. `comesTo` ends at something written out, so it
-  // never reaches a library's own function, and a project's alias of a
-  // library name has no answer at all. This follows the same aliases
-  // and barrels in the other direction and answers with the module and
-  // the name that module exports.
+  // source being read. A walk ends at something written out in source,
+  // so it never reaches a library's own function.
   rule(
     "comesFrom",
     [v("x"), v("m"), v("n")],
     [lit("imports", v("x"), v("m"), v("n"))]
   ),
-  rule(
-    "comesFrom",
-    [v("x"), v("m"), v("n")],
-    [lit("binds", v("x"), v("y")), lit("comesFrom", v("y"), v("m"), v("n"))]
-  ),
   rule(
     "comesFrom",
     [v("x"), v("m"), v("n")],
     [
-      lit("imports", v("x"), v("m2"), v("n2")),
-      lit("moduleExport", v("m2"), v("n2"), v("value")),
-      lit("comesFrom", v("value"), v("m"), v("n"))
+      lit("reaches", v("x"), v("y"), VALUE_STEP),
+      lit("imports", v("y"), v("m"), v("n"))
     ]
   ),
   // Calling f ends up calling the name n that module m exports. One hop
@@ -505,36 +579,6 @@ var RESOLUTION_RULES = [
     "resolves",
     [v("x"), v("z")],
     [lit("comesTo", v("x"), v("z")), lit("func", v("z"))]
-  ),
-  // Following a name to the expression it is written as. A separate
-  // relation rather than a widening of `comesTo`, so a caller asking
-  // the older question never sees a new answer: a factory call already
-  // has an unwrapping answer, and letting it also answer with itself
-  // would make that pair ambiguous.
-  //
-  // The two seeds are the two ways an expression can be written out. An
-  // object literal is one of them, and it is the shape a generated
-  // GraphQL document takes.
-  rule("isWrittenAs", [v("x"), v("x")], [lit("writtenValue", v("x"))]),
-  rule("isWrittenAs", [v("x"), v("x")], [lit("objectValue", v("x"))]),
-  rule(
-    "isWrittenAs",
-    [v("x"), v("z")],
-    [lit("binds", v("x"), v("y")), lit("isWrittenAs", v("y"), v("z"))]
-  ),
-  rule(
-    "isWrittenAs",
-    [v("x"), v("z")],
-    [lit("endsHolding", v("x"), v("y")), lit("isWrittenAs", v("y"), v("z"))]
-  ),
-  rule(
-    "isWrittenAs",
-    [v("x"), v("z")],
-    [
-      lit("imports", v("x"), v("m"), v("n")),
-      lit("moduleExport", v("m"), v("n"), v("value")),
-      lit("isWrittenAs", v("value"), v("z"))
-    ]
   )
 ];
 var RESOLUTION_QUESTIONS = [
@@ -566,6 +610,13 @@ var RESOLUTION_QUESTIONS = [
     [v("x"), v("z")],
     [lit("wanted", v("x")), lit("objectOf", v("x"), v("z"))]
   ),
+  // Keyed by the parameter, since that is what a caller has in hand
+  // when it wants the call sites told apart.
+  rule(
+    "wantedParamAt",
+    [v("p"), v("r"), v("z")],
+    [lit("wanted", v("p")), lit("paramAt", v("r"), v("p"), v("z"))]
+  ),
   rule(
     "wantedComesFrom",
     [v("x"), v("m"), v("n")],
@@ -589,5 +640,7 @@ export {
   FACT_CONTRACT_CASES,
   RESOLUTION_QUESTIONS,
   RESOLUTION_RULES,
+  RESULT_STEP,
+  VALUE_STEP,
   checkFactContract
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/resolution",
-  "version": "0.8.0",
+  "version": "0.10.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.8.0"
+    "@suss/datalog": "0.10.0"
   }
 }