@suss/resolution 0.34.1 → 0.35.1

package/dist/index.d.cts

@@ -296,6 +296,47 @@ declare class FactLog {
     changedValues(changed: ReadonlySet<string>, previous: ReadonlyMap<string, StoredFacts>): Set<number>;
 }
 
+/**
+ * What a call may run when it takes its function out of a table, or
+ * picks a member by a name it works out at run time: `COMMANDS[name](args)`,
+ * `handlers.get(kind)(event)`, `getattr(self, kind)()`, Ruby's `send(kind)`.
+ *
+ * The rules list every function such a call may run. Whether it runs
+ * exactly one is a count, which a rule cannot make, so it is decided
+ * here: the source has to narrow the read to one name, and the entry
+ * under that name has to be one function. Every other call may run any
+ * of the functions listed, and a caller records them as possible rather
+ * than as the one the call runs. DESIGN.md says which entries a read can
+ * come back with.
+ */
+
+/** What a call that takes its function from a table may run. */
+interface DispatchOutcome {
+    /** Every function the call may run, each once. */
+    readonly functions: readonly string[];
+    /** True when the source narrows the call to one entry that comes to one function. */
+    readonly certain: boolean;
+    /** How many entries came to no function this run read, any of which the call may run instead. */
+    readonly unresolved: number;
+    /** What each of `functions` calls in its own body, for an entry no summary describes, such as a lambda. */
+    readonly through: ReadonlyMap<string, readonly string[]>;
+    /** The tables and objects the call takes its function out of, for an adapter that reads their writes lazily. */
+    readonly containers: readonly string[];
+}
+/**
+ * The outcome for each of these calls that takes its function from a
+ * table. A call that does not is left out of the map. One question for
+ * the batch, so the rules are evaluated once.
+ */
+declare function dispatchOutcomes(db: Database, calls: readonly string[], program?: OnDemandRules): Map<string, DispatchOutcome>;
+/** What a caller asks through to learn what each call may run. */
+declare const DISPATCH_QUESTION = "wantedDispatch";
+/**
+ * The outcomes the rules derived for calls already asked about through
+ * `DISPATCH_QUESTION`, for a store that evaluates the rules itself.
+ */
+declare function readDispatchOutcomes(db: Database, calls: readonly string[]): Map<string, DispatchOutcome>;
+
 /**
  * Which records of a stored cache entry a run can replay, for an adapter
  * that stores one record per file: what the file's discovery depended
@@ -589,6 +630,14 @@ interface SpannedNode<N> {
     readonly parent: N | null;
     descendantForIndex(start: number, end: number): N | null;
 }
+/** Where a node key's node is written. */
+interface KeySpan {
+    readonly file: string;
+    readonly start: number;
+    readonly end: number;
+}
+/** The file and byte span of a node key, or null for a key that is not a node. */
+declare function spanOfKey(key: string): KeySpan | null;
 /**
  * The node a key refers to: the smallest node over the span, walked up
  * to the one whose span matches. A key that is not a node, such as a
@@ -1031,6 +1080,41 @@ declare function writtenValueUnder(db: Database, key: string, site: string, ask:
  */
 declare function allocationSitesOf(db: Database, cls: string): string[];
 
+/**
+ * Where each piece of a value written out in source goes: the entries of
+ * a list or an object, and the parts and holes of a template string.
+ *
+ * Every adapter states these rows from its own syntax, and a reader puts
+ * the value back together from them in any language. So the numbering
+ * is written once, here, and a list, an f-string and a Ruby interpolated
+ * symbol all count their pieces the same way.
+ */
+/** The last column of `writtenEntryAt` for an entry written in place. */
+declare const VALUE_ENTRY = "value";
+/** The last column of `writtenEntryAt` for a spread, which puts every entry of its collection at that one position. */
+declare const SPREAD_ENTRY = "spread";
+/** One entry of a list or an object: the key of its value, or of the collection a spread unpacks. */
+interface WrittenEntry {
+    readonly key: string;
+    readonly form: typeof VALUE_ENTRY | typeof SPREAD_ENTRY;
+}
+/** One piece of a template string: text it writes, or the key of a value it puts there. */
+type TemplatePiece = {
+    readonly text: string;
+} | {
+    readonly hole: string;
+};
+/** Adds one row to a relation, through whatever buffer the adapter keeps. */
+type AddRow = (relation: string, row: string[]) => void;
+/** `writtenEntryAt` for each entry of a list or an object, numbered in the order they are written. */
+declare function addEntryRows(add: AddRow, container: string, entries: readonly WrittenEntry[]): void;
+/**
+ * `partAt` and `holeAt` for a template's pieces, numbered together in
+ * source order. Text that writes nothing gets no row, so `${a}${b}` has
+ * two holes, at 0 and 1, and no parts.
+ */
+declare function addTemplateRows(add: AddRow, template: string, pieces: readonly TemplatePiece[]): void;
+
 /**
  * What a name written more than once comes down to.
  *
@@ -1203,4 +1287,4 @@ declare const ANSWER_RELATIONS: string[];
  */
 declare const UNDER_ANSWER_RELATIONS: string[];
 
-export { ANSWER_RELATIONS, ASKING_RELATIONS, type AskUnder, type AssociationConstructor, BASE_CLASS_RULE, type CalleeOutcome, type CaseFiles, type ChainReads, type Changes, type ContractCase, type ContractOptions, DEFAULT_IMPORT_NAME, type Dependencies, DependencyLedger, type DescribeAtom, type EntersAsSelf, EntryReuse, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, FactLog, type FactsOf, GLOBAL_MODULE, type GivesBackOne, type GivesBackOneOfArgument, type GivesBackOneOfImport, INSTANCE_STEP, type MountEdge, type MountEdges, NAMED_STORE_NAME, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, NAMESPACE_MEMBER_RULE, NAME_HOP_RULE, NO_CONTEXT, NO_CONTEXT_NAME, type NameReads, type NameWrite, type OrderedWrite, type PackWords, RECEIVER_STORE_NAME, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ReadNode, type ResolutionExplanation, type ResolutionStep, type SourceEnd, type SourceLeaf, type SourceQuestion, type SpannedNode, type StepContext, type StepPhrase, type StoredDependencies, type StoredFacts, type StoredFileRecord, type StoredWalkRecord, type SuppliesParameter, UNDER_ANSWER_RELATIONS, UNDER_QUESTION_ROW_BUDGET, UNDER_RUN_ROW_BUDGET, UNPLACED_STORE_NAME, USES_QUESTION, type UnderOutcome, type UnwrapsByName, VALUE_STEP, type ValueLocation, type ValueUses, WatchedMap, type WhyExplained, addPackWords, agreedMountPrefix, allocationSitesOf, alsoSteps, answersFor, answersFromTestsLeftOut, askResolution, askResolutionUnder, askSources, calleeOutcomeOf, calleeOutcomes, checkFactContract, classMemberName, classMemberOf, comesToUnder, couldBeSettled, declaredTypesOf, exitCodeFunctions, explainResolutionProof, explainResolvedKey, fallbackWrittenAs, fileOfKey, hashString, importedFilesByFile, isObserved, isWrittenAsUnder, joinMountedPath, mergeStoredDependencies, mountPathsOf, noDependencies, nodeOfKey, noteKeyRead, noteLookup, objectOfUnder, observeDemand, packHashes, proofRules, queryFacts, readUses, recordsToReplay, renderExplanation, resolutionProgram, resolutionUnderProgram, resolvedFunctions, settledFunction, sourceLeavesOf, startsAtName, staysInItsFunction, stillValid, underQuestionSpend, unpackHashes, valueLeftByWrites, walkRecordsByFile, writesRunInOrder, writtenAnswersFor, writtenSourcesOf, writtenValueOf, writtenValueUnder, writtenValuesByKey, writtenValuesOf };
+export { ANSWER_RELATIONS, ASKING_RELATIONS, type AddRow, type AskUnder, type AssociationConstructor, BASE_CLASS_RULE, type CalleeOutcome, type CaseFiles, type ChainReads, type Changes, type ContractCase, type ContractOptions, DEFAULT_IMPORT_NAME, DISPATCH_QUESTION, type Dependencies, DependencyLedger, type DescribeAtom, type DispatchOutcome, type EntersAsSelf, EntryReuse, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, FactLog, type FactsOf, GLOBAL_MODULE, type GivesBackOne, type GivesBackOneOfArgument, type GivesBackOneOfImport, INSTANCE_STEP, type KeySpan, type MountEdge, type MountEdges, NAMED_STORE_NAME, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, NAMESPACE_MEMBER_RULE, NAME_HOP_RULE, NO_CONTEXT, NO_CONTEXT_NAME, type NameReads, type NameWrite, type OrderedWrite, type PackWords, RECEIVER_STORE_NAME, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ReadNode, type ResolutionExplanation, type ResolutionStep, SPREAD_ENTRY, type SourceEnd, type SourceLeaf, type SourceQuestion, type SpannedNode, type StepContext, type StepPhrase, type StoredDependencies, type StoredFacts, type StoredFileRecord, type StoredWalkRecord, type SuppliesParameter, type TemplatePiece, UNDER_ANSWER_RELATIONS, UNDER_QUESTION_ROW_BUDGET, UNDER_RUN_ROW_BUDGET, UNPLACED_STORE_NAME, USES_QUESTION, type UnderOutcome, type UnwrapsByName, VALUE_ENTRY, VALUE_STEP, type ValueLocation, type ValueUses, WatchedMap, type WhyExplained, type WrittenEntry, addEntryRows, addPackWords, addTemplateRows, agreedMountPrefix, allocationSitesOf, alsoSteps, answersFor, answersFromTestsLeftOut, askResolution, askResolutionUnder, askSources, calleeOutcomeOf, calleeOutcomes, checkFactContract, classMemberName, classMemberOf, comesToUnder, couldBeSettled, declaredTypesOf, dispatchOutcomes, exitCodeFunctions, explainResolutionProof, explainResolvedKey, fallbackWrittenAs, fileOfKey, hashString, importedFilesByFile, isObserved, isWrittenAsUnder, joinMountedPath, mergeStoredDependencies, mountPathsOf, noDependencies, nodeOfKey, noteKeyRead, noteLookup, objectOfUnder, observeDemand, packHashes, proofRules, queryFacts, readDispatchOutcomes, readUses, recordsToReplay, renderExplanation, resolutionProgram, resolutionUnderProgram, resolvedFunctions, settledFunction, sourceLeavesOf, spanOfKey, startsAtName, staysInItsFunction, stillValid, underQuestionSpend, unpackHashes, valueLeftByWrites, walkRecordsByFile, writesRunInOrder, writtenAnswersFor, writtenSourcesOf, writtenValueOf, writtenValueUnder, writtenValuesByKey, writtenValuesOf };

package/dist/index.d.ts

@@ -296,6 +296,47 @@ declare class FactLog {
     changedValues(changed: ReadonlySet<string>, previous: ReadonlyMap<string, StoredFacts>): Set<number>;
 }
 
+/**
+ * What a call may run when it takes its function out of a table, or
+ * picks a member by a name it works out at run time: `COMMANDS[name](args)`,
+ * `handlers.get(kind)(event)`, `getattr(self, kind)()`, Ruby's `send(kind)`.
+ *
+ * The rules list every function such a call may run. Whether it runs
+ * exactly one is a count, which a rule cannot make, so it is decided
+ * here: the source has to narrow the read to one name, and the entry
+ * under that name has to be one function. Every other call may run any
+ * of the functions listed, and a caller records them as possible rather
+ * than as the one the call runs. DESIGN.md says which entries a read can
+ * come back with.
+ */
+
+/** What a call that takes its function from a table may run. */
+interface DispatchOutcome {
+    /** Every function the call may run, each once. */
+    readonly functions: readonly string[];
+    /** True when the source narrows the call to one entry that comes to one function. */
+    readonly certain: boolean;
+    /** How many entries came to no function this run read, any of which the call may run instead. */
+    readonly unresolved: number;
+    /** What each of `functions` calls in its own body, for an entry no summary describes, such as a lambda. */
+    readonly through: ReadonlyMap<string, readonly string[]>;
+    /** The tables and objects the call takes its function out of, for an adapter that reads their writes lazily. */
+    readonly containers: readonly string[];
+}
+/**
+ * The outcome for each of these calls that takes its function from a
+ * table. A call that does not is left out of the map. One question for
+ * the batch, so the rules are evaluated once.
+ */
+declare function dispatchOutcomes(db: Database, calls: readonly string[], program?: OnDemandRules): Map<string, DispatchOutcome>;
+/** What a caller asks through to learn what each call may run. */
+declare const DISPATCH_QUESTION = "wantedDispatch";
+/**
+ * The outcomes the rules derived for calls already asked about through
+ * `DISPATCH_QUESTION`, for a store that evaluates the rules itself.
+ */
+declare function readDispatchOutcomes(db: Database, calls: readonly string[]): Map<string, DispatchOutcome>;
+
 /**
  * Which records of a stored cache entry a run can replay, for an adapter
  * that stores one record per file: what the file's discovery depended
@@ -589,6 +630,14 @@ interface SpannedNode<N> {
     readonly parent: N | null;
     descendantForIndex(start: number, end: number): N | null;
 }
+/** Where a node key's node is written. */
+interface KeySpan {
+    readonly file: string;
+    readonly start: number;
+    readonly end: number;
+}
+/** The file and byte span of a node key, or null for a key that is not a node. */
+declare function spanOfKey(key: string): KeySpan | null;
 /**
  * The node a key refers to: the smallest node over the span, walked up
  * to the one whose span matches. A key that is not a node, such as a
@@ -1031,6 +1080,41 @@ declare function writtenValueUnder(db: Database, key: string, site: string, ask:
  */
 declare function allocationSitesOf(db: Database, cls: string): string[];
 
+/**
+ * Where each piece of a value written out in source goes: the entries of
+ * a list or an object, and the parts and holes of a template string.
+ *
+ * Every adapter states these rows from its own syntax, and a reader puts
+ * the value back together from them in any language. So the numbering
+ * is written once, here, and a list, an f-string and a Ruby interpolated
+ * symbol all count their pieces the same way.
+ */
+/** The last column of `writtenEntryAt` for an entry written in place. */
+declare const VALUE_ENTRY = "value";
+/** The last column of `writtenEntryAt` for a spread, which puts every entry of its collection at that one position. */
+declare const SPREAD_ENTRY = "spread";
+/** One entry of a list or an object: the key of its value, or of the collection a spread unpacks. */
+interface WrittenEntry {
+    readonly key: string;
+    readonly form: typeof VALUE_ENTRY | typeof SPREAD_ENTRY;
+}
+/** One piece of a template string: text it writes, or the key of a value it puts there. */
+type TemplatePiece = {
+    readonly text: string;
+} | {
+    readonly hole: string;
+};
+/** Adds one row to a relation, through whatever buffer the adapter keeps. */
+type AddRow = (relation: string, row: string[]) => void;
+/** `writtenEntryAt` for each entry of a list or an object, numbered in the order they are written. */
+declare function addEntryRows(add: AddRow, container: string, entries: readonly WrittenEntry[]): void;
+/**
+ * `partAt` and `holeAt` for a template's pieces, numbered together in
+ * source order. Text that writes nothing gets no row, so `${a}${b}` has
+ * two holes, at 0 and 1, and no parts.
+ */
+declare function addTemplateRows(add: AddRow, template: string, pieces: readonly TemplatePiece[]): void;
+
 /**
  * What a name written more than once comes down to.
  *
@@ -1203,4 +1287,4 @@ declare const ANSWER_RELATIONS: string[];
  */
 declare const UNDER_ANSWER_RELATIONS: string[];
 
-export { ANSWER_RELATIONS, ASKING_RELATIONS, type AskUnder, type AssociationConstructor, BASE_CLASS_RULE, type CalleeOutcome, type CaseFiles, type ChainReads, type Changes, type ContractCase, type ContractOptions, DEFAULT_IMPORT_NAME, type Dependencies, DependencyLedger, type DescribeAtom, type EntersAsSelf, EntryReuse, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, FactLog, type FactsOf, GLOBAL_MODULE, type GivesBackOne, type GivesBackOneOfArgument, type GivesBackOneOfImport, INSTANCE_STEP, type MountEdge, type MountEdges, NAMED_STORE_NAME, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, NAMESPACE_MEMBER_RULE, NAME_HOP_RULE, NO_CONTEXT, NO_CONTEXT_NAME, type NameReads, type NameWrite, type OrderedWrite, type PackWords, RECEIVER_STORE_NAME, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ReadNode, type ResolutionExplanation, type ResolutionStep, type SourceEnd, type SourceLeaf, type SourceQuestion, type SpannedNode, type StepContext, type StepPhrase, type StoredDependencies, type StoredFacts, type StoredFileRecord, type StoredWalkRecord, type SuppliesParameter, UNDER_ANSWER_RELATIONS, UNDER_QUESTION_ROW_BUDGET, UNDER_RUN_ROW_BUDGET, UNPLACED_STORE_NAME, USES_QUESTION, type UnderOutcome, type UnwrapsByName, VALUE_STEP, type ValueLocation, type ValueUses, WatchedMap, type WhyExplained, addPackWords, agreedMountPrefix, allocationSitesOf, alsoSteps, answersFor, answersFromTestsLeftOut, askResolution, askResolutionUnder, askSources, calleeOutcomeOf, calleeOutcomes, checkFactContract, classMemberName, classMemberOf, comesToUnder, couldBeSettled, declaredTypesOf, exitCodeFunctions, explainResolutionProof, explainResolvedKey, fallbackWrittenAs, fileOfKey, hashString, importedFilesByFile, isObserved, isWrittenAsUnder, joinMountedPath, mergeStoredDependencies, mountPathsOf, noDependencies, nodeOfKey, noteKeyRead, noteLookup, objectOfUnder, observeDemand, packHashes, proofRules, queryFacts, readUses, recordsToReplay, renderExplanation, resolutionProgram, resolutionUnderProgram, resolvedFunctions, settledFunction, sourceLeavesOf, startsAtName, staysInItsFunction, stillValid, underQuestionSpend, unpackHashes, valueLeftByWrites, walkRecordsByFile, writesRunInOrder, writtenAnswersFor, writtenSourcesOf, writtenValueOf, writtenValueUnder, writtenValuesByKey, writtenValuesOf };
+export { ANSWER_RELATIONS, ASKING_RELATIONS, type AddRow, type AskUnder, type AssociationConstructor, BASE_CLASS_RULE, type CalleeOutcome, type CaseFiles, type ChainReads, type Changes, type ContractCase, type ContractOptions, DEFAULT_IMPORT_NAME, DISPATCH_QUESTION, type Dependencies, DependencyLedger, type DescribeAtom, type DispatchOutcome, type EntersAsSelf, EntryReuse, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, FactLog, type FactsOf, GLOBAL_MODULE, type GivesBackOne, type GivesBackOneOfArgument, type GivesBackOneOfImport, INSTANCE_STEP, type KeySpan, type MountEdge, type MountEdges, NAMED_STORE_NAME, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, NAMESPACE_MEMBER_RULE, NAME_HOP_RULE, NO_CONTEXT, NO_CONTEXT_NAME, type NameReads, type NameWrite, type OrderedWrite, type PackWords, RECEIVER_STORE_NAME, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ReadNode, type ResolutionExplanation, type ResolutionStep, SPREAD_ENTRY, type SourceEnd, type SourceLeaf, type SourceQuestion, type SpannedNode, type StepContext, type StepPhrase, type StoredDependencies, type StoredFacts, type StoredFileRecord, type StoredWalkRecord, type SuppliesParameter, type TemplatePiece, UNDER_ANSWER_RELATIONS, UNDER_QUESTION_ROW_BUDGET, UNDER_RUN_ROW_BUDGET, UNPLACED_STORE_NAME, USES_QUESTION, type UnderOutcome, type UnwrapsByName, VALUE_ENTRY, VALUE_STEP, type ValueLocation, type ValueUses, WatchedMap, type WhyExplained, type WrittenEntry, addEntryRows, addPackWords, addTemplateRows, agreedMountPrefix, allocationSitesOf, alsoSteps, answersFor, answersFromTestsLeftOut, askResolution, askResolutionUnder, askSources, calleeOutcomeOf, calleeOutcomes, checkFactContract, classMemberName, classMemberOf, comesToUnder, couldBeSettled, declaredTypesOf, dispatchOutcomes, exitCodeFunctions, explainResolutionProof, explainResolvedKey, fallbackWrittenAs, fileOfKey, hashString, importedFilesByFile, isObserved, isWrittenAsUnder, joinMountedPath, mergeStoredDependencies, mountPathsOf, noDependencies, nodeOfKey, noteKeyRead, noteLookup, objectOfUnder, observeDemand, packHashes, proofRules, queryFacts, readDispatchOutcomes, readUses, recordsToReplay, renderExplanation, resolutionProgram, resolutionUnderProgram, resolvedFunctions, settledFunction, sourceLeavesOf, spanOfKey, startsAtName, staysInItsFunction, stillValid, underQuestionSpend, unpackHashes, valueLeftByWrites, walkRecordsByFile, writesRunInOrder, writtenAnswersFor, writtenSourcesOf, writtenValueOf, writtenValueUnder, writtenValuesByKey, writtenValuesOf };