@suss/resolution 0.20.0 → 0.21.1

package/README.md

@@ -97,6 +97,18 @@ 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.
 
+The closure is written with the walk so far first and the next hop after
+it: `reaches(x, z) <- reaches(x, y), stepsTo(y, z)`. The order matters
+under demand. Every question here asks about one value, and with the
+walk first, the demand stays on that value and each round extends the
+walks it already has by one hop. Written hop first, `reaches(x, z) <-
+stepsTo(x, y), reaches(y, z)`, a question about `x` becomes a question
+about every `y` a hop leads to, so the closure is derived from every
+value the walk passes through, and each new walk is joined back against
+every hop that lands on its start. Extracting the TypeScript adapter's
+own sources, the hop first order spent two seconds in the closure, and
+the walk first order spends forty milliseconds.
+
 ## What comes out
 
 ```
@@ -200,6 +212,32 @@ The demand cone stays on the base facts named above. Nothing here pulls
 `reaches` or `callsInto`, so asking about a receiver does not price in
 call-graph closure.
 
+## The subject behind a registration
+
+Discovery keeps asking one question: is this receiver the app, the
+router, the thing built by calling what a library exports? Which
+`.get(...)` calls are routes and which `.use(...)` calls are mounts
+both hang on the answer, and every language feature that moves a value
+is a place the receiver can be written: a class field, a destructured
+name, a property on an object another file built. Enumerating those
+spellings in a walker loses to the language, so the question is asked
+of the rules instead.
+
+The answer comes back in two relations, both seeded by
+`wantedSubject`.
+`wantedSubjectWritten` is the written-value walk from the asked
+receiver, so the asking side can apply the single-answer policy over
+everything the receiver could be. `wantedSubjectConstruction` keeps
+only the answers that are a call or a `new`, and pairs each with where
+its callee was imported from, through however many aliases the callee
+went. The asking side checks that pair against the (module, name) a
+pack declares: exactly one distinct construction with a matching
+origin is the subject, none or several is a refusal.
+
+The construction end needs no fact of its own. Every call is already a
+`call` fact, a `new` expression included, and the join against
+`comesFrom` is what makes one of them a subject seed.
+
 ## Explaining an answer
 
 Evaluate the same rules under `@suss/datalog`'s `witnesses` algebra and

package/dist/index.cjs

@@ -631,9 +631,9 @@ var RESOLUTION_RULES = [
     [(0, import_datalog2.lit)("invokes", (0, import_datalog2.variable)("r"), (0, import_datalog2.variable)("f")), (0, import_datalog2.lit)("returnsValue", (0, import_datalog2.variable)("f"), (0, import_datalog2.variable)("ret"))],
     "call result"
   ),
-  // 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.
+  // Where a walk gets to, and whether it ran a call on the way. The walk
+  // so far comes first, so demand stays on the value asked about; the
+  // README says what the other order cost.
   (0, import_datalog2.rule)(
     "reaches",
     [(0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("z"), (0, import_datalog2.variable)("kind")],
@@ -643,27 +643,27 @@ var RESOLUTION_RULES = [
     "reaches",
     [(0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("z"), (0, import_datalog2.variable)("kind")],
     [
-      (0, import_datalog2.lit)("stepsTo", (0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("y"), VALUE_STEP),
-      (0, import_datalog2.lit)("reaches", (0, import_datalog2.variable)("y"), (0, import_datalog2.variable)("z"), (0, import_datalog2.variable)("kind"))
+      (0, import_datalog2.lit)("reaches", (0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("y"), VALUE_STEP),
+      (0, import_datalog2.lit)("stepsTo", (0, import_datalog2.variable)("y"), (0, import_datalog2.variable)("z"), (0, import_datalog2.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
+  // Two rules rather than one leaving the next step'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_datalog2.rule)(
     "reaches",
     [(0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("z"), RESULT_STEP],
     [
-      (0, import_datalog2.lit)("stepsTo", (0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("y"), RESULT_STEP),
-      (0, import_datalog2.lit)("reaches", (0, import_datalog2.variable)("y"), (0, import_datalog2.variable)("z"), VALUE_STEP)
+      (0, import_datalog2.lit)("reaches", (0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("y"), RESULT_STEP),
+      (0, import_datalog2.lit)("stepsTo", (0, import_datalog2.variable)("y"), (0, import_datalog2.variable)("z"), VALUE_STEP)
     ]
   ),
   (0, import_datalog2.rule)(
     "reaches",
     [(0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("z"), RESULT_STEP],
     [
-      (0, import_datalog2.lit)("stepsTo", (0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("y"), RESULT_STEP),
-      (0, import_datalog2.lit)("reaches", (0, import_datalog2.variable)("y"), (0, import_datalog2.variable)("z"), RESULT_STEP)
+      (0, import_datalog2.lit)("reaches", (0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("y"), RESULT_STEP),
+      (0, import_datalog2.lit)("stepsTo", (0, import_datalog2.variable)("y"), (0, import_datalog2.variable)("z"), RESULT_STEP)
     ]
   ),
   // What a value comes down to: the walk that never ran a call, stopped
@@ -1009,29 +1009,14 @@ var RESOLUTION_QUESTIONS = [
   // here demands reaches or callsInto. The chains are closures with
   // no depth bound: an alias run of any length resolves.
   (0, import_datalog2.rule)("callOriginChain", [(0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("x")], [(0, import_datalog2.lit)("wantedCallOrigin", (0, import_datalog2.variable)("x"))]),
+  // The chain with at least one hop taken, which is what tells a
+  // destructured binding apart from asking about a node directly. The
+  // whole chain is the seed plus those hops.
   (0, import_datalog2.rule)(
     "callOriginChain",
     [(0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("z")],
-    [(0, import_datalog2.lit)("callOriginChain", (0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("y")), (0, import_datalog2.lit)("binds", (0, import_datalog2.variable)("y"), (0, import_datalog2.variable)("z"))]
+    [(0, import_datalog2.lit)("callOriginChainStepped", (0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("z"))]
   ),
-  (0, import_datalog2.rule)(
-    "callOriginChain",
-    [(0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("z")],
-    [
-      (0, import_datalog2.lit)("callOriginChain", (0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("y")),
-      (0, import_datalog2.lit)("endsHolding", (0, import_datalog2.variable)("y"), (0, import_datalog2.variable)("z"))
-    ]
-  ),
-  (0, import_datalog2.rule)(
-    "callOriginChain",
-    [(0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("z")],
-    [
-      (0, import_datalog2.lit)("callOriginChain", (0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("y")),
-      (0, import_datalog2.lit)("fallbackBranch", (0, import_datalog2.variable)("y"), (0, import_datalog2.variable)("z"))
-    ]
-  ),
-  // The chain with at least one hop taken, which is what tells a
-  // destructured binding apart from asking about a node directly.
   (0, import_datalog2.rule)(
     "callOriginChainStepped",
     [(0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("z")],
@@ -1162,6 +1147,23 @@ var RESOLUTION_QUESTIONS = [
       (0, import_datalog2.lit)("callsInto", (0, import_datalog2.variable)("g"), (0, import_datalog2.variable)("m"), (0, import_datalog2.variable)("n"))
     ]
   ),
+  // Subject identity, its own demand class; the README's subject
+  // section says why the origin pair rides on the written-value walk.
+  (0, import_datalog2.rule)(
+    "wantedSubjectWritten",
+    [(0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("r")],
+    [(0, import_datalog2.lit)("wantedSubject", (0, import_datalog2.variable)("x")), (0, import_datalog2.lit)("isWrittenAs", (0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("r"))]
+  ),
+  (0, import_datalog2.rule)(
+    "wantedSubjectConstruction",
+    [(0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("r"), (0, import_datalog2.variable)("m"), (0, import_datalog2.variable)("n")],
+    [
+      (0, import_datalog2.lit)("wantedSubject", (0, import_datalog2.variable)("x")),
+      (0, import_datalog2.lit)("isWrittenAs", (0, import_datalog2.variable)("x"), (0, import_datalog2.variable)("r")),
+      (0, import_datalog2.lit)("call", (0, import_datalog2.variable)("r"), (0, import_datalog2.variable)("c")),
+      (0, import_datalog2.lit)("comesFrom", (0, import_datalog2.variable)("c"), (0, import_datalog2.variable)("m"), (0, import_datalog2.variable)("n"))
+    ]
+  ),
   // The export table of one module, keyed by the module asked about.
   // The moduleExport rules flatten re-export chains of any length, and
   // the demand cone stays on export facts alone.

package/dist/index.js

@@ -592,9 +592,9 @@ var RESOLUTION_RULES = [
     [lit("invokes", v("r"), v("f")), lit("returnsValue", v("f"), v("ret"))],
     "call result"
   ),
-  // 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.
+  // Where a walk gets to, and whether it ran a call on the way. The walk
+  // so far comes first, so demand stays on the value asked about; the
+  // README says what the other order cost.
   rule(
     "reaches",
     [v("x"), v("z"), v("kind")],
@@ -604,27 +604,27 @@ var RESOLUTION_RULES = [
     "reaches",
     [v("x"), v("z"), v("kind")],
     [
-      lit("stepsTo", v("x"), v("y"), VALUE_STEP),
-      lit("reaches", v("y"), v("z"), v("kind"))
+      lit("reaches", v("x"), v("y"), VALUE_STEP),
+      lit("stepsTo", 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
+  // Two rules rather than one leaving the next step'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)
+      lit("reaches", v("x"), v("y"), RESULT_STEP),
+      lit("stepsTo", 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)
+      lit("reaches", v("x"), v("y"), RESULT_STEP),
+      lit("stepsTo", v("y"), v("z"), RESULT_STEP)
     ]
   ),
   // What a value comes down to: the walk that never ran a call, stopped
@@ -970,29 +970,14 @@ var RESOLUTION_QUESTIONS = [
   // here demands reaches or callsInto. The chains are closures with
   // no depth bound: an alias run of any length resolves.
   rule("callOriginChain", [v("x"), v("x")], [lit("wantedCallOrigin", v("x"))]),
+  // The chain with at least one hop taken, which is what tells a
+  // destructured binding apart from asking about a node directly. The
+  // whole chain is the seed plus those hops.
   rule(
     "callOriginChain",
     [v("x"), v("z")],
-    [lit("callOriginChain", v("x"), v("y")), lit("binds", v("y"), v("z"))]
+    [lit("callOriginChainStepped", v("x"), v("z"))]
   ),
-  rule(
-    "callOriginChain",
-    [v("x"), v("z")],
-    [
-      lit("callOriginChain", v("x"), v("y")),
-      lit("endsHolding", v("y"), v("z"))
-    ]
-  ),
-  rule(
-    "callOriginChain",
-    [v("x"), v("z")],
-    [
-      lit("callOriginChain", v("x"), v("y")),
-      lit("fallbackBranch", v("y"), v("z"))
-    ]
-  ),
-  // The chain with at least one hop taken, which is what tells a
-  // destructured binding apart from asking about a node directly.
   rule(
     "callOriginChainStepped",
     [v("x"), v("z")],
@@ -1123,6 +1108,23 @@ var RESOLUTION_QUESTIONS = [
       lit("callsInto", v("g"), v("m"), v("n"))
     ]
   ),
+  // Subject identity, its own demand class; the README's subject
+  // section says why the origin pair rides on the written-value walk.
+  rule(
+    "wantedSubjectWritten",
+    [v("x"), v("r")],
+    [lit("wantedSubject", v("x")), lit("isWrittenAs", v("x"), v("r"))]
+  ),
+  rule(
+    "wantedSubjectConstruction",
+    [v("x"), v("r"), v("m"), v("n")],
+    [
+      lit("wantedSubject", v("x")),
+      lit("isWrittenAs", v("x"), v("r")),
+      lit("call", v("r"), v("c")),
+      lit("comesFrom", v("c"), v("m"), v("n"))
+    ]
+  ),
   // The export table of one module, keyed by the module asked about.
   // The moduleExport rules flatten re-export chains of any length, and
   // the demand cone stays on export facts alone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/resolution",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "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.20.0"
+    "@suss/datalog": "0.21.1"
   }
 }