@suss/resolution 0.22.1 → 0.22.3

package/dist/index.cjs

@@ -34,9 +34,11 @@ __export(index_exports, {
   explainResolvedKey: () => explainResolvedKey,
   joinMountedPath: () => joinMountedPath,
   mountPathsOf: () => mountPathsOf,
+  nodeOfKey: () => nodeOfKey,
   placeholderValues: () => placeholderValues,
   renderExplanation: () => renderExplanation,
-  singleAnswers: () => singleAnswers
+  singleAnswers: () => singleAnswers,
+  writtenValueOf: () => writtenValueOf
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -519,6 +521,32 @@ function pathsOf(edges, memo, childId, visiting) {
   return result;
 }
 
+// src/nodeKey.ts
+var SPAN_KEY = /^(.*):(\d+)-(\d+)$/;
+function nodeOfKey(rootsByFile, key) {
+  const span = key.match(SPAN_KEY);
+  if (span === null) {
+    return null;
+  }
+  const root = rootsByFile.get(span[1]);
+  const start = Number(span[2]);
+  const end = Number(span[3]);
+  if (root === void 0 || end <= start) {
+    return null;
+  }
+  let current = root.descendantForIndex(start, end - 1);
+  while (current !== null) {
+    if (current.startIndex === start && current.endIndex === end) {
+      return current;
+    }
+    if (current.startIndex < start || current.endIndex > end) {
+      return null;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+
 // src/session.ts
 var import_datalog2 = require("@suss/datalog");
 function explainResolvedKey(options) {
@@ -606,6 +634,26 @@ function withoutPlaceholders(answers, placeholders) {
   return kept;
 }
 
+// src/writtenValue.ts
+function writtenValueOf(db, key, ask) {
+  const placeholders = placeholderValues(db);
+  const direct = singleAnswers(db.facts("wantedIsWrittenAs"), placeholders).get(
+    key
+  );
+  if (direct === void 0) {
+    return null;
+  }
+  const isCall = db.facts("call").some((row) => String(row[0]) === direct);
+  if (!isCall) {
+    return direct;
+  }
+  ask([direct]);
+  const deeper = singleAnswers(db.facts("wantedIsWrittenAs"), placeholders).get(
+    direct
+  );
+  return deeper ?? direct;
+}
+
 // src/index.ts
 var import_datalog3 = require("@suss/datalog");
 var VALUE_STEP = (0, import_datalog3.constant)("value");
@@ -1361,7 +1409,9 @@ var ANSWER_RELATIONS = [
   explainResolvedKey,
   joinMountedPath,
   mountPathsOf,
+  nodeOfKey,
   placeholderValues,
   renderExplanation,
-  singleAnswers
+  singleAnswers,
+  writtenValueOf
 });

package/dist/index.d.cts

@@ -148,6 +148,25 @@ declare function mountPathsOf(edges: MountEdges, childId: string): readonly stri
  */
 declare function agreedMountPrefix(edges: MountEdges, childId: string): string | null;
 
+/**
+ * The tree-sitter adapters key a node by its file and byte span,
+ * `file:start-end`. This finds the node a key refers to again, for an
+ * evaluator that gets a key back from the facts and needs the syntax.
+ */
+/** What a tree-sitter node offers for finding it by span again. */
+interface SpannedNode<N> {
+    readonly startIndex: number;
+    readonly endIndex: number;
+    readonly parent: N | null;
+    descendantForIndex(start: number, end: number): N | 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
+ * name, has none.
+ */
+declare function nodeOfKey<N extends SpannedNode<N>>(rootsByFile: ReadonlyMap<string, N>, key: string): N | null;
+
 /**
  * The result shape a why session hands back, shared by every language
  * adapter so the CLI reads one type regardless of which adapter
@@ -224,6 +243,14 @@ declare function singleAnswers(rows: Iterable<Tuple>, placeholders?: ReadonlySet
 /** The keys an adapter marked `placeholderValue`, for passing to `singleAnswers`. */
 declare function placeholderValues(db: Database): ReadonlySet<string>;
 
+/**
+ * The single expression a value was written as, once the caller has
+ * asked the rules about `key`. A call to a project function is asked
+ * about as well, through `ask`, so the answer is what that function
+ * returns rather than the call itself.
+ */
+declare function writtenValueOf(db: Database, key: string, ask: (keys: readonly string[]) => void): string | null;
+
 /** A step to the value x is written as. */
 declare const VALUE_STEP: _suss_datalog.Term;
 /**
@@ -272,4 +299,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, type DescribeAtom, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, type FactsOf, type MountEdge, type MountEdges, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ResolutionExplanation, type ResolutionStep, type StepContext, type StepPhrase, VALUE_STEP, type ValueLocation, type WhyExplained, agreedMountPrefix, checkFactContract, explainResolutionProof, explainResolvedKey, joinMountedPath, mountPathsOf, placeholderValues, renderExplanation, singleAnswers };
+export { ANSWER_RELATIONS, type CaseFiles, type ContractCase, type ContractOptions, type DescribeAtom, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, type FactsOf, type MountEdge, type MountEdges, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ResolutionExplanation, type ResolutionStep, type SpannedNode, type StepContext, type StepPhrase, VALUE_STEP, type ValueLocation, type WhyExplained, agreedMountPrefix, checkFactContract, explainResolutionProof, explainResolvedKey, joinMountedPath, mountPathsOf, nodeOfKey, placeholderValues, renderExplanation, singleAnswers, writtenValueOf };

package/dist/index.d.ts

@@ -148,6 +148,25 @@ declare function mountPathsOf(edges: MountEdges, childId: string): readonly stri
  */
 declare function agreedMountPrefix(edges: MountEdges, childId: string): string | null;
 
+/**
+ * The tree-sitter adapters key a node by its file and byte span,
+ * `file:start-end`. This finds the node a key refers to again, for an
+ * evaluator that gets a key back from the facts and needs the syntax.
+ */
+/** What a tree-sitter node offers for finding it by span again. */
+interface SpannedNode<N> {
+    readonly startIndex: number;
+    readonly endIndex: number;
+    readonly parent: N | null;
+    descendantForIndex(start: number, end: number): N | 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
+ * name, has none.
+ */
+declare function nodeOfKey<N extends SpannedNode<N>>(rootsByFile: ReadonlyMap<string, N>, key: string): N | null;
+
 /**
  * The result shape a why session hands back, shared by every language
  * adapter so the CLI reads one type regardless of which adapter
@@ -224,6 +243,14 @@ declare function singleAnswers(rows: Iterable<Tuple>, placeholders?: ReadonlySet
 /** The keys an adapter marked `placeholderValue`, for passing to `singleAnswers`. */
 declare function placeholderValues(db: Database): ReadonlySet<string>;
 
+/**
+ * The single expression a value was written as, once the caller has
+ * asked the rules about `key`. A call to a project function is asked
+ * about as well, through `ask`, so the answer is what that function
+ * returns rather than the call itself.
+ */
+declare function writtenValueOf(db: Database, key: string, ask: (keys: readonly string[]) => void): string | null;
+
 /** A step to the value x is written as. */
 declare const VALUE_STEP: _suss_datalog.Term;
 /**
@@ -272,4 +299,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, type DescribeAtom, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, type FactsOf, type MountEdge, type MountEdges, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ResolutionExplanation, type ResolutionStep, type StepContext, type StepPhrase, VALUE_STEP, type ValueLocation, type WhyExplained, agreedMountPrefix, checkFactContract, explainResolutionProof, explainResolvedKey, joinMountedPath, mountPathsOf, placeholderValues, renderExplanation, singleAnswers };
+export { ANSWER_RELATIONS, type CaseFiles, type ContractCase, type ContractOptions, type DescribeAtom, type ExplainOptions, type ExplainResolvedKeyOptions, type ExplainStats, FACT_CONTRACT_CASES, type FactsOf, type MountEdge, type MountEdges, NAMESPACE_IMPORT, NAMESPACE_IMPORT_NAME, RESOLUTION_QUESTIONS, RESOLUTION_RULES, RESULT_STEP, type ResolutionExplanation, type ResolutionStep, type SpannedNode, type StepContext, type StepPhrase, VALUE_STEP, type ValueLocation, type WhyExplained, agreedMountPrefix, checkFactContract, explainResolutionProof, explainResolvedKey, joinMountedPath, mountPathsOf, nodeOfKey, placeholderValues, renderExplanation, singleAnswers, writtenValueOf };

package/dist/index.js

@@ -477,6 +477,32 @@ function pathsOf(edges, memo, childId, visiting) {
   return result;
 }
 
+// src/nodeKey.ts
+var SPAN_KEY = /^(.*):(\d+)-(\d+)$/;
+function nodeOfKey(rootsByFile, key) {
+  const span = key.match(SPAN_KEY);
+  if (span === null) {
+    return null;
+  }
+  const root = rootsByFile.get(span[1]);
+  const start = Number(span[2]);
+  const end = Number(span[3]);
+  if (root === void 0 || end <= start) {
+    return null;
+  }
+  let current = root.descendantForIndex(start, end - 1);
+  while (current !== null) {
+    if (current.startIndex === start && current.endIndex === end) {
+      return current;
+    }
+    if (current.startIndex < start || current.endIndex > end) {
+      return null;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+
 // src/session.ts
 import { Database, evaluate, proofOf, witnesses } from "@suss/datalog";
 function explainResolvedKey(options) {
@@ -564,6 +590,26 @@ function withoutPlaceholders(answers, placeholders) {
   return kept;
 }
 
+// src/writtenValue.ts
+function writtenValueOf(db, key, ask) {
+  const placeholders = placeholderValues(db);
+  const direct = singleAnswers(db.facts("wantedIsWrittenAs"), placeholders).get(
+    key
+  );
+  if (direct === void 0) {
+    return null;
+  }
+  const isCall = db.facts("call").some((row) => String(row[0]) === direct);
+  if (!isCall) {
+    return direct;
+  }
+  ask([direct]);
+  const deeper = singleAnswers(db.facts("wantedIsWrittenAs"), placeholders).get(
+    direct
+  );
+  return deeper ?? direct;
+}
+
 // src/index.ts
 import { constant, lit, rule, variable as v } from "@suss/datalog";
 var VALUE_STEP = constant("value");
@@ -1318,7 +1364,9 @@ export {
   explainResolvedKey,
   joinMountedPath,
   mountPathsOf,
+  nodeOfKey,
   placeholderValues,
   renderExplanation,
-  singleAnswers
+  singleAnswers,
+  writtenValueOf
 };

package/package.json

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