@suss/resolution 0.3.2 → 0.5.0

package/README.md

@@ -1,19 +1,20 @@
 # @suss/resolution
 
-The rules for following a value to the function it comes down to.
+The rules for following a value to the function it ends up being.
 
 ## What this package is
 
-A list of Datalog rules and nothing else. No parser, no language, no
-files. An adapter reads source into facts, concatenates its own rules
-onto these, and evaluates on `@suss/datalog`.
+A list of Datalog rules, and nothing else. It has no parser, no
+language, and no files of its own. An adapter reads source into facts,
+adds its own rules onto these, and evaluates the whole set on
+`@suss/datalog`.
 
-The rules are about programming languages rather than about any one of
-them. A name binds to a value. A call puts an argument in a parameter. A
-module exports a name and another module can forward it. A function that
-returns a function calling its parameter hands back the argument it was
-given, which is a decorator in Python, a closure in Go, and a handler
-factory in TypeScript.
+The rules are about programming languages in general rather than about
+any one of them. A name binds to a value. A call puts an argument in a
+parameter. A module exports a name, and another module can forward it.
+A function that returns a function calling its parameter hands back the
+argument it was given, which is a decorator in Python, a closure in Go,
+and a handler factory in TypeScript.
 
 ## The facts an adapter supplies
 
@@ -28,6 +29,8 @@ binds(x, y)                 the name x is declared as y
 endsHolding(x, y)           the name x is written more than once and
                             holds y once the writes have run
 paramOf(f, k, p)            p is f's parameter at position k
+paramNamed(f, n, p)         p is f's parameter called n
+extends(c, b)               class c is written as extending b
 returnsValue(f, v)          f returns v
 bodyCalls(f, c)             f's body calls c
 containsFn(f, g)            g is declared inside f
@@ -41,9 +44,16 @@ reExportsAll(m, m2)         m forwards everything m2 exports
 
 Two more come from a pack rather than from source, for a wrapper whose
 body nobody can read: `unwrapsByName(name, k)` and
-`wrapperModule(name, module)`, checked against `calleeName` and
-`calleeOrigin` so a local function spelled like the library's does not
-match.
+`wrapperModule(name, module)`. Both are checked against `calleeName` and
+`calleeOrigin`, so a local function that happens to be spelled the same
+as the library's does not match.
+
+`holdsProperty` is something an adapter states and the rules only read.
+What a value contains, a base class included, comes out as `contains`,
+so a method a base declares is found on a subclass that never overrode
+it. Deriving that into `holdsProperty` instead turns it from a fact into
+a derived relation, and the on-demand rewrite then gates it behind a
+demand nothing generates.
 
 Node identity is the adapter's business. The rules only join on it.
 
@@ -58,87 +68,89 @@ callsInto(f, m, n)          calling f ends up calling m's n
 ```
 
 `resolves` is the question most callers ask. `comesTo` is the one
-underneath it, and it can answer with an object, since a chain has to
-pass through objects for `routes.list` to reach what `list` holds.
+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.
 
 `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
 reaches one.
 
-`comesFrom` answers the direction `comesTo` cannot. Every `comesTo`
-chain ends at something written out in the source being read, so a name
-for a library's own function ends nowhere: the library's body is not
-here. `comesFrom` follows the same aliases, imports and barrels and
-answers with the module and the name that module exports.
+`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.
 
 `callsInto` puts that together with the calls a function makes. A
 project writes its own decorator that calls `Resolver()` and applies
 that one to its classes, and the class is a resolver even though nothing
-about it says `Resolver`. Several answers for one function is the normal
-case rather than an ambiguity, since a wrapper composing two library
-decorators applies both, so a caller asks whether the one it cares about
-is among them.
+about it says `Resolver`. Getting several answers for one function is
+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 comes out for the rules' own use rather than for callers:
+One relation exists for the rules' own use rather than for callers:
 
 ```
 objectOf(x, obj)            x stands for the object literal obj
 ```
 
 An object arrives two ways, through a name or as what a factory call
-returns, and `objectOf` names that step 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, since a
-factory call usually is the wrapper and answering with the function it
-returns would fight the unwrapping answer.
+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.
 
 ## Why rules and not a walker
 
 Each rule describes one hop. The chains people write are longer than
 that, and nobody writes a rule for them: a factory handing off to
 another factory, a closure three levels down calling the argument, a
-barrel re-exporting a wrapper. The engine composes what it has, so those
-work without being named.
+barrel re-exporting a wrapper. The engine composes what it has, so all
+of those work without anyone writing a rule for them.
 
-The corollary is where to look when something comes back empty. Suspect
-the facts before the rules. Against one production service suss
+That tells you where to look when something comes back empty. Suspect
+the facts before the rules. Against one production service, suss
 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 unchanged.
+the rest without any change.
 
 ## What is not modelled
 
 **A handler passed as one property of a config.** `make({ body:
-handler })`, where the factory reads `opts.body`, does not resolve. A
-rule for it was tried and taken out: a wrapper often reads several
+handler })`, where the factory reads `opts.body`, does not resolve. We
+tried a rule for it and took it back out. A wrapper often reads several
 callbacks off the same config object, the rule made each one a
-candidate for the whole call, and the resulting ambiguity nulled out
-handlers that used to resolve. Saying which property is the handler
-takes something structure does not carry,
-either "the only property called" (which needs negation) or a pack
-naming the property. Until one of those exists, this shape stays
+candidate for the whole call, and the ambiguity that produced nulled out
+handlers that used to resolve. Working out which property is the handler
+needs something the structure does not tell you: either "the only
+property that gets called" (which needs negation) or a pack that says
+which property it is. Until one of those exists, this pattern stays
 unresolved on purpose.
 
 **An element of an array.** `all[0]` has no fact for what an array
-holds.
+contains.
 
 **Which write a read sees, once control flow decides it.** A name
-written twice in a module's own statement list is answered: those
+written twice in a module's own statement list does resolve. Those
 statements run once each, top to bottom, so the last write is what
 anything importing the name gets, and the adapter says so with
 `endsHolding`. A write inside a branch, a loop, or a function body is a
-different claim, and the adapter stays quiet. The name then comes to
-nothing, which is the answer until there are control-flow facts to
-reason over.
+different claim, and the adapter says nothing about it. The name then
+resolves to nothing, and it stays that way until we have control-flow
+facts to reason over.
 
-Answering it in general is reaching definitions, per use rather than
+Answering that in general is reaching definitions, per use rather than
 per name. That needs facts saying which statement follows which and
-which branch each sits on, and no adapter emits any today.
+which branch each one is in, and no adapter emits any of those today.
 
-The adapter picking the write rather than a rule picking it is a cost
-decision. Ordering writes inside the rules means asking which writes
-have no later write, negation says that in one line, and this
+We have the adapter pick the write rather than a rule, and that is a
+cost decision. Ordering writes inside the rules means asking which
+writes have no later write. Negation says that in one line, but this
 evaluator has to throw its last fixpoint away and start over whenever a
 rule set uses negation. The store evaluates after every wave of facts,
 so one negated rule turned a 66 second run on the Saleor dashboard into
@@ -146,8 +158,8 @@ one that had not finished in ten minutes. Source order is something
 every adapter already knows.
 
 **Ambiguity is the caller's problem.** When the rules reach two
-different functions the store returns nothing, since picking one would
-make the answer depend on the order facts arrived in.
+different functions, the store returns nothing, because picking one
+would make the answer depend on the order the facts arrived in.
 
 ## License
 

package/dist/index.cjs

@@ -21,10 +21,166 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   ANSWER_RELATIONS: () => ANSWER_RELATIONS,
+  FACT_CONTRACT_CASES: () => FACT_CONTRACT_CASES,
   RESOLUTION_QUESTIONS: () => RESOLUTION_QUESTIONS,
-  RESOLUTION_RULES: () => RESOLUTION_RULES
+  RESOLUTION_RULES: () => RESOLUTION_RULES,
+  checkFactContract: () => checkFactContract
 });
 module.exports = __toCommonJS(index_exports);
+
+// src/contract.ts
+var distinct = (values) => new Set(values).size;
+var RELATIONS_THAT_CAN_CROSS = ["imports", "binds", "reExports"];
+var FACT_CONTRACT_CASES = [
+  {
+    name: "two functions, one parameter name",
+    requires: "two functions in one file, each declaring a parameter of the same name",
+    check: (facts) => {
+      const params = facts("paramOf").map((row) => row[2] ?? "");
+      if (params.length < 2) {
+        return `expected two parameters, found ${params.length}`;
+      }
+      return distinct(params) === params.length ? null : "two parameters share a key, so a value is keyed by its name rather than by the node that declares it";
+    }
+  },
+  {
+    name: "a name read inside a function",
+    requires: "a function with a parameter, whose body reads that parameter and returns it",
+    // An adapter may key the read as the parameter itself, or as its own
+    // node linked by `binds`. Both join; what fails is a read that reaches
+    // its declaration by neither.
+    check: (facts) => {
+      const param = facts("paramOf")[0]?.[2];
+      const returned = facts("returnsValue")[0]?.[1];
+      if (param === void 0 || returned === void 0) {
+        return "expected one parameter and one return";
+      }
+      if (param === returned) {
+        return null;
+      }
+      const linked = facts("binds").some(
+        (row) => row[0] === returned && row[1] === param
+      );
+      return linked ? null : "a read of a parameter is neither the parameter nor bound to it, so a read and its declaration never join";
+    }
+  },
+  {
+    name: "a name bound to a call",
+    requires: "a module-level name assigned the result of a call",
+    check: (facts) => {
+      const call = facts("call")[0]?.[0];
+      if (call === void 0) {
+        return "expected one call";
+      }
+      const written = facts("writtenValue").some((row) => row[0] === call);
+      if (!written) {
+        return "a call is not a written value, so a chain ending at one derives nothing through isWrittenAs";
+      }
+      return facts("comesTo").some((row) => row[0] === call) ? "a call has a comesTo, which the rules withhold on purpose so a factory call does not answer with what it returns" : null;
+    }
+  },
+  {
+    name: "a written-out sequence",
+    requires: "a module-level name assigned a written-out list of two names",
+    check: (facts) => {
+      if (facts("objectValue").length === 0) {
+        return "a sequence is not an object value, so nothing can be read out of it";
+      }
+      const keys = facts("holdsProperty").map((row) => row[1] ?? "");
+      if (keys.length < 2) {
+        return `a sequence keeps no elements: expected two, found ${keys.length}`;
+      }
+      return keys.includes("0") && keys.includes("1") ? null : `a sequence keeps its elements under ${JSON.stringify(keys)} rather than their positions, so one property rule cannot cover indexed access`;
+    }
+  },
+  {
+    name: "a module exporting a name",
+    requires: "a module-level function declaration",
+    check: (facts) => {
+      const exported = facts("exportsAs")[0];
+      if (exported === void 0) {
+        return "a module exports nothing, so no other file can reach into it";
+      }
+      const value = exported[2] ?? "";
+      return facts("func").some((row) => row[0] === value) ? null : "what a module exports is not the node that declares it";
+    }
+  },
+  {
+    name: "a class declaring a method",
+    requires: "a module-level class with one method, exported where a language says so",
+    check: (facts) => {
+      const objects = new Set(facts("objectValue").map((row) => row[0]));
+      if (objects.size === 0) {
+        return "a class is not an object value, so nothing can be read off an instance of it";
+      }
+      const functions = new Set(facts("func").map((row) => row[0]));
+      const contained = facts("holdsProperty").filter(
+        (row) => objects.has(row[0])
+      );
+      if (contained.length === 0) {
+        return "a class contains none of its methods, so a method read off an instance resolves to nothing";
+      }
+      return contained.some((row) => functions.has(row[2])) ? null : "what a class contains under a method name is not the node that declares the method";
+    }
+  },
+  {
+    name: "a value another file declares",
+    requires: "two files, one declaring a value and the other reading it by name",
+    // Which relation says so is the language's business. TypeScript and Python
+    // both write an import; Ruby has none and binds the reading site straight
+    // to the definition. What has to be true is that some fact reaches out of
+    // the file doing the reading into the file doing the declaring.
+    check: (facts, files) => {
+      if (files.length < 2) {
+        return "expected two files";
+      }
+      const mentions = (value, file) => value.includes(file);
+      const crosses = RELATIONS_THAT_CAN_CROSS.some(
+        (relation) => facts(relation).some(
+          (row) => files.some(
+            (from) => mentions(row[0] ?? "", from) && row.slice(1).some(
+              (cell) => files.some((to) => to !== from && mentions(cell, to))
+            )
+          )
+        )
+      );
+      return crosses ? null : "nothing links a name read in one file to what another file declares, so a value cannot leave the file it is written in";
+    }
+  }
+];
+function checkFactContract(sources, emit, options = {}) {
+  return FACT_CONTRACT_CASES.reduce(async (soFar, contractCase) => {
+    const failures = await soFar;
+    const files = sources[contractCase.name];
+    if (files === void 0) {
+      return [
+        ...failures,
+        {
+          case: contractCase.name,
+          problem: `no source supplied for: ${contractCase.requires}`
+        }
+      ];
+    }
+    const db = await emit(files);
+    const problem = contractCase.check(
+      (relation) => db.facts(relation).map((row) => row.map(String)),
+      Object.keys(files)
+    );
+    const known = options.known?.[contractCase.name];
+    if (known !== void 0) {
+      return problem === null ? [
+        ...failures,
+        {
+          case: contractCase.name,
+          problem: `written down as a known gap (${known}) and now satisfied, so take it off the list`
+        }
+      ] : failures;
+    }
+    return problem === null ? failures : [...failures, { case: contractCase.name, problem }];
+  }, Promise.resolve([]));
+}
+
+// src/index.ts
 var import_datalog = require("@suss/datalog");
 var RESOLUTION_RULES = [
   // A value comes to itself; every chain ends at something written out
@@ -37,7 +193,7 @@ var RESOLUTION_RULES = [
     [(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"))]
   ),
-  // A name written more than once holds the value the last write left
+  // 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
@@ -79,7 +235,7 @@ 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 stands for. A name arrives at one by
+  // 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
@@ -101,6 +257,92 @@ var RESOLUTION_RULES = [
       (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
+  // the function and wants its call sites, so both of these start from
+  // the function. Starting from `call` instead asks what every call in
+  // the project imports, which was 72% of everything derived.
+  (0, import_datalog.rule)(
+    "callsFunction",
+    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("f")],
+    [(0, import_datalog.lit)("binds", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("f")), (0, import_datalog.lit)("call", (0, import_datalog.variable)("r"), (0, import_datalog.variable)("c"))]
+  ),
+  (0, import_datalog.rule)(
+    "callsFunction",
+    [(0, import_datalog.variable)("r"), (0, import_datalog.variable)("f")],
+    [
+      (0, import_datalog.lit)("moduleExport", (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("f")),
+      (0, import_datalog.lit)("imports", (0, import_datalog.variable)("c"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")),
+      (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
+  // rather than more `holdsProperty`, which stays something an adapter
+  // states and the rules only read.
+  (0, import_datalog.rule)(
+    "contains",
+    [(0, import_datalog.variable)("o"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("held")],
+    [(0, import_datalog.lit)("holdsProperty", (0, import_datalog.variable)("o"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("held"))]
+  ),
+  (0, import_datalog.rule)(
+    "contains",
+    [(0, import_datalog.variable)("cls"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("held")],
+    [
+      (0, import_datalog.lit)("extends", (0, import_datalog.variable)("cls"), (0, import_datalog.variable)("base")),
+      (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("base"), (0, import_datalog.variable)("baseCls")),
+      (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.
@@ -110,7 +352,7 @@ var RESOLUTION_RULES = [
     [
       (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)("holdsProperty", (0, import_datalog.variable)("obj"), (0, import_datalog.variable)("n"), (0, import_datalog.variable)("held")),
+      (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"))
     ]
   ),
@@ -203,7 +445,7 @@ var RESOLUTION_RULES = [
       (0, import_datalog.lit)("comesTo", (0, import_datalog.variable)("a"), (0, import_datalog.variable)("h"))
     ]
   ),
-  // Where a name comes from, when what it names lives outside the
+  // 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
@@ -314,6 +556,14 @@ 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)("isWrittenAs", (0, import_datalog.variable)("x"), (0, import_datalog.variable)("z"))]
   ),
+  // A call is given no `comesTo`, so this is the only way to ask what
+  // object one arrives at, and without it a demand-driven run derives
+  // `objectOf` nowhere.
+  (0, import_datalog.rule)(
+    "wantedObjectOf",
+    [(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"))]
+  ),
   (0, import_datalog.rule)(
     "wantedComesFrom",
     [(0, import_datalog.variable)("x"), (0, import_datalog.variable)("m"), (0, import_datalog.variable)("n")],
@@ -335,6 +585,8 @@ var ANSWER_RELATIONS = [
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ANSWER_RELATIONS,
+  FACT_CONTRACT_CASES,
   RESOLUTION_QUESTIONS,
-  RESOLUTION_RULES
+  RESOLUTION_RULES,
+  checkFactContract
 });

package/dist/index.d.cts

@@ -1,4 +1,40 @@
 import * as _suss_datalog from '@suss/datalog';
+import { Database } from '@suss/datalog';
+
+/** The tuples of one relation, as strings, which is all a case compares. */
+type FactsOf = (relation: string) => string[][];
+interface ContractCase {
+    /** The key an adapter supplies its own source under. */
+    readonly name: string;
+    /** What that source has to contain, for whoever writes it. */
+    readonly requires: string;
+    /**
+     * Null when the facts satisfy the case; otherwise what is wrong with them.
+     * `files` is the source file names the adapter supplied, so a case about a
+     * value leaving its file can say which file it should have left.
+     */
+    readonly check: (facts: FactsOf, files: readonly string[]) => string | null;
+}
+declare const FACT_CONTRACT_CASES: readonly ContractCase[];
+/** One case's source, as the files it takes, because a value leaving its file takes two. */
+type CaseFiles = Readonly<Record<string, string>>;
+interface ContractOptions {
+    /**
+     * Cases the adapter is known not to satisfy, each with why. A known case
+     * that starts passing is reported too, so a gap that gets closed does not
+     * stay written down as one.
+     */
+    readonly known?: Readonly<Record<string, string>>;
+}
+/**
+ * Every case an adapter fails, with what is wrong. Empty when the adapter
+ * satisfies the contract. `emit` reads the files a case supplies and gives
+ * back the facts the adapter produced for them.
+ */
+declare function checkFactContract(sources: Readonly<Record<string, CaseFiles>>, emit: (files: CaseFiles) => Promise<Database> | Database, options?: ContractOptions): Promise<{
+    case: string;
+    problem: string;
+}[]>;
 
 /**
  * The rules every language adapter shares. Concatenate a language's own
@@ -8,7 +44,7 @@ declare const RESOLUTION_RULES: _suss_datalog.Rule[];
 /**
  * The questions a caller asks, written as rules. Two facts say somebody
  * is asking: `wanted(x)` for what a value is, and `wantedOrigin(x)` for
- * where a name came from. Each answer relation holds the pairs for the
+ * where a name came from. Each answer relation contains the pairs for the
  * values somebody asked about, keyed by the value asked about, which is
  * the key the caller looks up by anyway.
  *
@@ -26,4 +62,4 @@ declare const RESOLUTION_QUESTIONS: _suss_datalog.Rule[];
 /** The relations `RESOLUTION_QUESTIONS` answers into. */
 declare const ANSWER_RELATIONS: string[];
 
-export { ANSWER_RELATIONS, RESOLUTION_QUESTIONS, RESOLUTION_RULES };
+export { ANSWER_RELATIONS, type CaseFiles, type ContractCase, type ContractOptions, FACT_CONTRACT_CASES, type FactsOf, RESOLUTION_QUESTIONS, RESOLUTION_RULES, checkFactContract };

package/dist/index.d.ts

@@ -1,4 +1,40 @@
 import * as _suss_datalog from '@suss/datalog';
+import { Database } from '@suss/datalog';
+
+/** The tuples of one relation, as strings, which is all a case compares. */
+type FactsOf = (relation: string) => string[][];
+interface ContractCase {
+    /** The key an adapter supplies its own source under. */
+    readonly name: string;
+    /** What that source has to contain, for whoever writes it. */
+    readonly requires: string;
+    /**
+     * Null when the facts satisfy the case; otherwise what is wrong with them.
+     * `files` is the source file names the adapter supplied, so a case about a
+     * value leaving its file can say which file it should have left.
+     */
+    readonly check: (facts: FactsOf, files: readonly string[]) => string | null;
+}
+declare const FACT_CONTRACT_CASES: readonly ContractCase[];
+/** One case's source, as the files it takes, because a value leaving its file takes two. */
+type CaseFiles = Readonly<Record<string, string>>;
+interface ContractOptions {
+    /**
+     * Cases the adapter is known not to satisfy, each with why. A known case
+     * that starts passing is reported too, so a gap that gets closed does not
+     * stay written down as one.
+     */
+    readonly known?: Readonly<Record<string, string>>;
+}
+/**
+ * Every case an adapter fails, with what is wrong. Empty when the adapter
+ * satisfies the contract. `emit` reads the files a case supplies and gives
+ * back the facts the adapter produced for them.
+ */
+declare function checkFactContract(sources: Readonly<Record<string, CaseFiles>>, emit: (files: CaseFiles) => Promise<Database> | Database, options?: ContractOptions): Promise<{
+    case: string;
+    problem: string;
+}[]>;
 
 /**
  * The rules every language adapter shares. Concatenate a language's own
@@ -8,7 +44,7 @@ declare const RESOLUTION_RULES: _suss_datalog.Rule[];
 /**
  * The questions a caller asks, written as rules. Two facts say somebody
  * is asking: `wanted(x)` for what a value is, and `wantedOrigin(x)` for
- * where a name came from. Each answer relation holds the pairs for the
+ * where a name came from. Each answer relation contains the pairs for the
  * values somebody asked about, keyed by the value asked about, which is
  * the key the caller looks up by anyway.
  *
@@ -26,4 +62,4 @@ declare const RESOLUTION_QUESTIONS: _suss_datalog.Rule[];
 /** The relations `RESOLUTION_QUESTIONS` answers into. */
 declare const ANSWER_RELATIONS: string[];
 
-export { ANSWER_RELATIONS, RESOLUTION_QUESTIONS, RESOLUTION_RULES };
+export { ANSWER_RELATIONS, type CaseFiles, type ContractCase, type ContractOptions, FACT_CONTRACT_CASES, type FactsOf, RESOLUTION_QUESTIONS, RESOLUTION_RULES, checkFactContract };

package/dist/index.js

@@ -1,3 +1,155 @@
+// src/contract.ts
+var distinct = (values) => new Set(values).size;
+var RELATIONS_THAT_CAN_CROSS = ["imports", "binds", "reExports"];
+var FACT_CONTRACT_CASES = [
+  {
+    name: "two functions, one parameter name",
+    requires: "two functions in one file, each declaring a parameter of the same name",
+    check: (facts) => {
+      const params = facts("paramOf").map((row) => row[2] ?? "");
+      if (params.length < 2) {
+        return `expected two parameters, found ${params.length}`;
+      }
+      return distinct(params) === params.length ? null : "two parameters share a key, so a value is keyed by its name rather than by the node that declares it";
+    }
+  },
+  {
+    name: "a name read inside a function",
+    requires: "a function with a parameter, whose body reads that parameter and returns it",
+    // An adapter may key the read as the parameter itself, or as its own
+    // node linked by `binds`. Both join; what fails is a read that reaches
+    // its declaration by neither.
+    check: (facts) => {
+      const param = facts("paramOf")[0]?.[2];
+      const returned = facts("returnsValue")[0]?.[1];
+      if (param === void 0 || returned === void 0) {
+        return "expected one parameter and one return";
+      }
+      if (param === returned) {
+        return null;
+      }
+      const linked = facts("binds").some(
+        (row) => row[0] === returned && row[1] === param
+      );
+      return linked ? null : "a read of a parameter is neither the parameter nor bound to it, so a read and its declaration never join";
+    }
+  },
+  {
+    name: "a name bound to a call",
+    requires: "a module-level name assigned the result of a call",
+    check: (facts) => {
+      const call = facts("call")[0]?.[0];
+      if (call === void 0) {
+        return "expected one call";
+      }
+      const written = facts("writtenValue").some((row) => row[0] === call);
+      if (!written) {
+        return "a call is not a written value, so a chain ending at one derives nothing through isWrittenAs";
+      }
+      return facts("comesTo").some((row) => row[0] === call) ? "a call has a comesTo, which the rules withhold on purpose so a factory call does not answer with what it returns" : null;
+    }
+  },
+  {
+    name: "a written-out sequence",
+    requires: "a module-level name assigned a written-out list of two names",
+    check: (facts) => {
+      if (facts("objectValue").length === 0) {
+        return "a sequence is not an object value, so nothing can be read out of it";
+      }
+      const keys = facts("holdsProperty").map((row) => row[1] ?? "");
+      if (keys.length < 2) {
+        return `a sequence keeps no elements: expected two, found ${keys.length}`;
+      }
+      return keys.includes("0") && keys.includes("1") ? null : `a sequence keeps its elements under ${JSON.stringify(keys)} rather than their positions, so one property rule cannot cover indexed access`;
+    }
+  },
+  {
+    name: "a module exporting a name",
+    requires: "a module-level function declaration",
+    check: (facts) => {
+      const exported = facts("exportsAs")[0];
+      if (exported === void 0) {
+        return "a module exports nothing, so no other file can reach into it";
+      }
+      const value = exported[2] ?? "";
+      return facts("func").some((row) => row[0] === value) ? null : "what a module exports is not the node that declares it";
+    }
+  },
+  {
+    name: "a class declaring a method",
+    requires: "a module-level class with one method, exported where a language says so",
+    check: (facts) => {
+      const objects = new Set(facts("objectValue").map((row) => row[0]));
+      if (objects.size === 0) {
+        return "a class is not an object value, so nothing can be read off an instance of it";
+      }
+      const functions = new Set(facts("func").map((row) => row[0]));
+      const contained = facts("holdsProperty").filter(
+        (row) => objects.has(row[0])
+      );
+      if (contained.length === 0) {
+        return "a class contains none of its methods, so a method read off an instance resolves to nothing";
+      }
+      return contained.some((row) => functions.has(row[2])) ? null : "what a class contains under a method name is not the node that declares the method";
+    }
+  },
+  {
+    name: "a value another file declares",
+    requires: "two files, one declaring a value and the other reading it by name",
+    // Which relation says so is the language's business. TypeScript and Python
+    // both write an import; Ruby has none and binds the reading site straight
+    // to the definition. What has to be true is that some fact reaches out of
+    // the file doing the reading into the file doing the declaring.
+    check: (facts, files) => {
+      if (files.length < 2) {
+        return "expected two files";
+      }
+      const mentions = (value, file) => value.includes(file);
+      const crosses = RELATIONS_THAT_CAN_CROSS.some(
+        (relation) => facts(relation).some(
+          (row) => files.some(
+            (from) => mentions(row[0] ?? "", from) && row.slice(1).some(
+              (cell) => files.some((to) => to !== from && mentions(cell, to))
+            )
+          )
+        )
+      );
+      return crosses ? null : "nothing links a name read in one file to what another file declares, so a value cannot leave the file it is written in";
+    }
+  }
+];
+function checkFactContract(sources, emit, options = {}) {
+  return FACT_CONTRACT_CASES.reduce(async (soFar, contractCase) => {
+    const failures = await soFar;
+    const files = sources[contractCase.name];
+    if (files === void 0) {
+      return [
+        ...failures,
+        {
+          case: contractCase.name,
+          problem: `no source supplied for: ${contractCase.requires}`
+        }
+      ];
+    }
+    const db = await emit(files);
+    const problem = contractCase.check(
+      (relation) => db.facts(relation).map((row) => row.map(String)),
+      Object.keys(files)
+    );
+    const known = options.known?.[contractCase.name];
+    if (known !== void 0) {
+      return problem === null ? [
+        ...failures,
+        {
+          case: contractCase.name,
+          problem: `written down as a known gap (${known}) and now satisfied, so take it off the list`
+        }
+      ] : failures;
+    }
+    return problem === null ? failures : [...failures, { case: contractCase.name, problem }];
+  }, Promise.resolve([]));
+}
+
 // src/index.ts
 import { lit, rule, variable as v } from "@suss/datalog";
 var RESOLUTION_RULES = [
@@ -11,7 +163,7 @@ var RESOLUTION_RULES = [
     [v("x"), v("z")],
     [lit("binds", v("x"), v("y")), lit("comesTo", v("y"), v("z"))]
   ),
-  // A name written more than once holds the value the last write left
+  // 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
@@ -53,7 +205,7 @@ var RESOLUTION_RULES = [
       lit("moduleExport", v("m2"), v("n"), v("value"))
     ]
   ),
-  // The object an expression stands for. A name arrives at one by
+  // 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
@@ -75,6 +227,92 @@ var RESOLUTION_RULES = [
       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
+  // the function and wants its call sites, so both of these start from
+  // the function. Starting from `call` instead asks what every call in
+  // the project imports, which was 72% of everything derived.
+  rule(
+    "callsFunction",
+    [v("r"), v("f")],
+    [lit("binds", v("c"), v("f")), lit("call", v("r"), v("c"))]
+  ),
+  rule(
+    "callsFunction",
+    [v("r"), v("f")],
+    [
+      lit("moduleExport", v("m"), v("n"), v("f")),
+      lit("imports", v("c"), v("m"), v("n")),
+      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
+  // rather than more `holdsProperty`, which stays something an adapter
+  // states and the rules only read.
+  rule(
+    "contains",
+    [v("o"), v("n"), v("held")],
+    [lit("holdsProperty", v("o"), v("n"), v("held"))]
+  ),
+  rule(
+    "contains",
+    [v("cls"), v("n"), v("held")],
+    [
+      lit("extends", v("cls"), v("base")),
+      lit("comesTo", v("base"), v("baseCls")),
+      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.
@@ -84,7 +322,7 @@ var RESOLUTION_RULES = [
     [
       lit("readsProperty", v("x"), v("o"), v("n")),
       lit("objectOf", v("o"), v("obj")),
-      lit("holdsProperty", v("obj"), v("n"), v("held")),
+      lit("contains", v("obj"), v("n"), v("held")),
       lit("comesTo", v("held"), v("z"))
     ]
   ),
@@ -177,7 +415,7 @@ var RESOLUTION_RULES = [
       lit("comesTo", v("a"), v("h"))
     ]
   ),
-  // Where a name comes from, when what it names lives outside the
+  // 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
@@ -288,6 +526,14 @@ var RESOLUTION_QUESTIONS = [
     [v("x"), v("z")],
     [lit("wanted", v("x")), lit("isWrittenAs", v("x"), v("z"))]
   ),
+  // A call is given no `comesTo`, so this is the only way to ask what
+  // object one arrives at, and without it a demand-driven run derives
+  // `objectOf` nowhere.
+  rule(
+    "wantedObjectOf",
+    [v("x"), v("z")],
+    [lit("wanted", v("x")), lit("objectOf", v("x"), v("z"))]
+  ),
   rule(
     "wantedComesFrom",
     [v("x"), v("m"), v("n")],
@@ -308,6 +554,8 @@ var ANSWER_RELATIONS = [
 ];
 export {
   ANSWER_RELATIONS,
+  FACT_CONTRACT_CASES,
   RESOLUTION_QUESTIONS,
-  RESOLUTION_RULES
+  RESOLUTION_RULES,
+  checkFactContract
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/resolution",
-  "version": "0.3.2",
+  "version": "0.5.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.3.2"
+    "@suss/datalog": "0.5.0"
   }
 }