@suss/resolution 0.10.0 → 0.11.0

package/README.md

@@ -28,6 +28,8 @@ readsProperty(x, o, n)      x is the expression o.n
 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
+fallbackBranch(x, b)        x is a fallback expression and b is one
+                            of its branches
 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
@@ -79,6 +81,18 @@ 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.
 
+A fallback expression (`a || b`, `a ?? b`, Python's `a or b`) says its
+value is one of its branches, so each branch is a value step. That is
+the whole rule. When one branch is something no static reader can
+settle, a global cache or a parameter, that branch derives nothing, and
+the branch that does resolve is the only claim the source makes. The
+idiomatic client singleton, `global.prisma || new PrismaClient()`, is
+exactly this: the global read makes no claim, so the construction is
+the answer. When both branches resolve to different things, both
+derive, and the caller's single-answer policy refuses the pair. That is
+the same refusal every other two-candidate chain gets, because a value
+that is one of two different things is not one thing.
+
 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.
@@ -159,6 +173,30 @@ 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.
 
+## Explaining an answer
+
+Evaluate the same rules under `@suss/datalog`'s `witnesses` algebra and
+every derived fact keeps the rule that fired and the facts it consumed,
+so `proofOf` can rebuild the derivation tree of any answer on demand.
+`explainResolutionProof` flattens that tree into the chain a person
+reads: the step rules are the hops, `reaches` is the glue between them,
+and the base cases ("x is already a function") end a chain without
+adding to it. Each hop comes back with one sentence saying why it is
+true, written from the rule's own name: `alias`, `import`, `argument`,
+`factory unwrap`, and so on.
+
+Two kinds of detail ride under a hop rather than beside it. A barrel
+chain under an `import` hop lists which files forwarded the name. A
+`declared wrapper` hop rests on a pack's word rather than on source, so
+it surfaces as an assumption: "a pack declares that withSentry from
+@sentry/serverless passes argument 0 through to its result". A proof
+cut short by the depth cap says so instead of trailing off.
+
+Atoms in a proof are whatever node ids the adapter interned, so both
+functions take a `describe` callback that says an atom in source terms.
+`renderExplanation` turns the flattened chain into printable lines;
+`suss ask 'why does … reach …'` is this pipeline end to end.
+
 ## Why rules and not a walker
 
 Each rule describes one hop. The chains people write are longer than