@ttsc/graph 0.19.3 → 0.20.0

package/src/server/resultAudit.ts

@@ -26,12 +26,22 @@
  * anything was checked afterwards — lost two points and put the file reads
  * back.
  *
- * So the weight is carried by the second party, not by the loud voice. The
- * compiler resolving a fact is where the fact came from; the server checking it
- * again on the way out is why the reader does not have to. Say both, in that
- * order, and the instruction that follows reads as a conclusion rather than a
- * demand. Never mystify the result, and never insult the reader for checking
- * it.
+ * So the weight is carried by named provenance, not by a loud voice. State who
+ * resolved the fact and what this payload did with it, and the instruction that
+ * follows reads as a conclusion rather than a demand. Never mystify the result,
+ * and never insult the reader for checking it.
+ *
+ * The claim has to be one this code can keep. An earlier wording said the
+ * server assembled the result and "verified them again on the way out" — a
+ * second pass, by a second party, after assembly. No such pass exists: this
+ * layer holds no `Program` and no checker, it runs one pure projection over an
+ * in-memory `TtscGraphMemory`, and it selects a constant by request type
+ * (#818). What is true is stronger than it sounds and is what the text now
+ * says: the compiler resolved these facts when the snapshot was built, the
+ * graph holds what it resolved, and this result is a projection of exactly
+ * those facts that adds none of its own. A reader who checks that claim finds
+ * it holds; a reader who checked the old one found a promise the code could not
+ * have kept.
  *
  * ## Two guarantees, not one
  *
@@ -47,18 +57,18 @@
  * payload, and told it to stop where the shortlist's coverage was exactly what
  * needed judging.
  *
- * So the audits split by what the reader must judge. {@link RESULT_AUDIT}
- * covers the walks from an explicit handle or structure (`trace`, `overview`):
- * the result is what the graph holds for what you named, bounded where
- * `truncated` says. {@link RESULT_AUDIT_DETAILS} covers `details`, whose result
- * is not one bounded whole but two halves — a symbol's own shape, returned
- * complete, and its fan-out, returned as a slice with `trace` for the rest — so
- * it names which half to trust outright and which to follow. {@link
- * RESULT_AUDIT_SELECTION} covers the ranked shortlists (`lookup`, `entrypoints`,
- * `tour`): it keeps the same fact-verification and adds that the _selection_ is
- * heuristic, so whether the shortlist covers the question is the caller's to
- * judge — and a follow-up request or a read of a cited span is a sound next
- * step, not a failure to trust the result.
+ * So the audits split by what the reader must judge. {@link RESULT_AUDIT} covers
+ * the walks from an explicit handle or structure (`trace`, `overview`): the
+ * result is what the graph holds for what you named, bounded where `truncated`
+ * says. {@link RESULT_AUDIT_DETAILS} covers `details`, whose result is not one
+ * bounded whole but two halves — a symbol's own shape, returned complete, and
+ * its fan-out, returned as a slice with `trace` for the rest — so it names
+ * which half to trust outright and which to follow.
+ * {@link RESULT_AUDIT_SELECTION} covers the ranked shortlists (`lookup`,
+ * `entrypoints`, `tour`): it keeps the same fact-verification and adds that the
+ * _selection_ is heuristic, so whether the shortlist covers the question is the
+ * caller's to judge — and a follow-up request or a read of a cited span is a
+ * sound next step, not a failure to trust the result.
  *
  * Keep both narrow, and keep the stop-or-continue decision with the result's
  * `next`, so neither contradicts a partial result that legitimately asks for
@@ -69,10 +79,10 @@
 export const RESULT_AUDIT: string = `
 AUDITED BEFORE RETURNING. READ FIRST.
 
-The server assembled this \`result\`, then checked it: every fact in it — each name, span,
-edge, signature, and step — was taken back to the type-checked program for the snapshot this
-call synced to, and resolved there. The compiler resolved these facts and the server
-verified them again on the way out, so for this snapshot a fact here cannot be wrong.
+Every fact in this \`result\` — each name, span, edge, signature, and step — was resolved by
+the TypeScript compiler against the program for the snapshot this call synced to, and the
+graph holds what it resolved. This \`result\` is a projection of exactly those facts and adds
+none of its own, so for this snapshot a fact here cannot disagree with the program.
 
 This is the structure the graph holds for the handles you named, not a shortlist matched
 against a natural-language question. Trust every fact it gives and re-verify none: a returned
@@ -92,11 +102,11 @@ after you edit the source.
 export const RESULT_AUDIT_SELECTION: string = `
 AUDITED BEFORE RETURNING. READ FIRST.
 
-Each fact in this \`result\` — every name, span, edge, and signature — was taken back to the
-type-checked program for the snapshot this call synced to, and resolved there. The compiler
-resolved these facts and the server verified them again on the way out, so for this snapshot
-a fact here cannot be wrong: a returned span is the citation, not a cue to open the file to
-confirm it.
+Each fact in this \`result\` — every name, span, edge, and signature — was resolved by the
+TypeScript compiler against the program for the snapshot this call synced to, and the graph
+holds what it resolved. This \`result\` is a projection of exactly those facts and adds none of
+its own, so for this snapshot a fact here cannot disagree with the program: a returned span
+is the citation, not a cue to open the file to confirm it.
 
 What was selected is heuristic, not exhaustive. This result was matched against your
 natural-language question, scored and ranked, held to a few hits per file, and cut to a
@@ -113,10 +123,10 @@ Follow \`next\` for where that leaves the question.
  *
  * `trace` walks and marks where the walk was cut with `truncated`; `details`
  * does not walk. It resolves a named handle, and its result splits in two. What
- * a symbol *is* — its members, its values, its signature — is bounded by the
+ * a symbol _is_ — its members, its values, its signature — is bounded by the
  * declaration and returned whole, so the old "trust it, do not open the file"
  * is finally true of it rather than contradicted by a capped member list. What
- * a symbol *reaches or is reached by* — its calls, its type references, its
+ * a symbol _reaches or is reached by_ — its calls, its type references, its
  * implementers, its dependents — is bounded by how widely it is used, not by
  * the symbol, so returning it whole is a `trace`/impact answer of a thousand
  * refs in a "what is this" call. That half is a short orientation slice, and
@@ -127,10 +137,10 @@ Follow \`next\` for where that leaves the question.
 export const RESULT_AUDIT_DETAILS: string = `
 AUDITED BEFORE RETURNING. READ FIRST.
 
-The server assembled this \`result\`, then checked it: every fact in it — each name, span,
-edge, signature, member, and value — was taken back to the type-checked program for the
-snapshot this call synced to, and resolved there, so for this snapshot a fact here cannot be
-wrong.
+Every fact in this \`result\` — each name, span, edge, signature, member, and value — was
+resolved by the TypeScript compiler against the program for the snapshot this call synced to,
+and the graph holds what it resolved. This \`result\` is a projection of exactly those facts
+and adds none of its own, so for this snapshot a fact here cannot disagree with the program.
 
 This is the structure the graph holds for the handles you named. What a symbol is — its
 members, its values, its signature — is complete: trust it and do not open the file to read
@@ -143,6 +153,27 @@ Follow \`next\`: answer from this result, and re-call the graph only when it say
 after you edit the source.
 `.trim();
 
+/**
+ * The details audit for a result whose member list a caller cap truncated.
+ *
+ * The unconditional text tells the reader a symbol's members are complete and
+ * not to open the file for them. After `memberLimit` cuts the list that is
+ * false, and it is the one claim a caller cannot check from the result: the
+ * members that were removed left nothing behind to notice. So the claim is
+ * withdrawn for exactly that half and everything else the audit verifies is
+ * kept.
+ */
+export const RESULT_AUDIT_DETAILS_CAPPED: string = RESULT_AUDIT_DETAILS.replace(
+  // Matched by shape rather than by exact spelling. This file is stored with
+  // CRLF, so a needle carrying a plain newline never matches the template
+  // literal's real line breaks and the replacement would silently do nothing —
+  // the capped audit would come out identical to the uncapped one.
+  /What a symbol is[\s\S]*?what is already here\./,
+  "What a symbol is — its values and its signature — is complete. Its member list was cut to " +
+    "the `memberLimit` you asked for, so it is a slice, not the whole set: re-request with a " +
+    "larger cap for the rest.",
+);
+
 /** The escape branch carries no graph facts, so it claims none. */
 export const RESULT_AUDIT_ESCAPE: string =
   "This escape carries no graph facts to audit.";

package/src/server/resultNext.ts

@@ -7,6 +7,12 @@ export interface IRunnerOutput<T> {
 
   /** How to use the result next. */
   next: ITtscGraphNext;
+
+  /**
+   * Set when a caller cap removed members from the result, so the audit can
+   * stop claiming the symbol's members are complete.
+   */
+  membersCapped?: boolean;
 }
 
 export function resultNext(

package/src/server/runDetails.ts

@@ -1,6 +1,3 @@
-import fs from "node:fs";
-import path from "node:path";
-
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
 import { ITtscGraphDecorator } from "../structures/ITtscGraphDecorator";
 import { ITtscGraphDetails } from "../structures/ITtscGraphDetails";
@@ -15,9 +12,6 @@ import { IRunnerOutput, resultNext } from "./resultNext";
 const MAX_SIGNATURE_LINES = 4;
 // A doc summary is one sentence; the rest of the comment is the file's to keep.
 const MAX_DOC_CHARS = 200;
-// An object literal's outline is scanned from source, so a runaway literal is
-// bounded here; the members it does find are not capped.
-const MAX_OBJECT_MEMBER_LINES = 300;
 // A symbol's fan-out — what it calls, what names it in a type, what depends on
 // it — scales with how popular it is, not with the symbol: a central type is
 // named in a thousand places, and returning all of them is a hundred thousand
@@ -57,7 +51,15 @@ export function runDetails(
   // does not: what names or uses a symbol is bounded by its popularity, not by
   // it, so those stay a small slice with `trace` for the rest.
   const memberLimit = limitOf(props.memberLimit);
-  const neighborLimit = capOf(props.neighborLimit, DEFAULT_NEIGHBORS, MAX_NEIGHBORS);
+  // True once any handle's member list is cut by the cap above. It travels with
+  // the result so the audit can withdraw the completeness claim for exactly
+  // that half — a caller cannot notice the cut from the result itself.
+  let membersCapped = false;
+  const neighborLimit = capOf(
+    props.neighborLimit,
+    DEFAULT_NEIGHBORS,
+    MAX_NEIGHBORS,
+  );
   const dependencyLimit = capOf(
     props.dependencyLimit,
     DEFAULT_DEPENDENCIES,
@@ -100,9 +102,9 @@ export function runDetails(
       file: node.file,
     };
     if (node.evidence?.startLine) detail.line = node.evidence.startLine;
-    const sig = signatureOf(graph.project, node);
+    const sig = signatureOf(graph, node);
     if (sig !== undefined) detail.signature = sig;
-    const doc = docOf(graph.project, node);
+    const doc = docOf(graph, node);
     if (doc !== undefined) detail.doc = doc;
     const decorators = decoratorsOf(node);
     if (decorators !== undefined) detail.decorators = decorators;
@@ -141,16 +143,19 @@ export function runDetails(
     );
     if (implementedBy.length > 0) detail.implementedBy = implementedBy;
     if (CONTAINER_KINDS.has(node.kind)) {
-      const list = members(graph, node, memberLimit);
-      if (list.length > 0) detail.members = list;
+      // Read one past the cap so the cut is observable. Without it a full list
+      // and a truncated one are the same value, and the audit went on claiming
+      // the members were whole.
+      const list = members(graph, node, memberLimit + 1);
+      if (list.length > memberLimit) membersCapped = true;
+      const shown = list.slice(0, memberLimit);
+      if (shown.length > 0) detail.members = shown;
     }
-    if (node.kind === "variable" && detail.sourceSpan !== undefined) {
-      const list = objectLiteralMembers(
-        graph.project,
-        detail.sourceSpan,
-        memberLimit,
-      );
-      if (list.length > 0) detail.members = list;
+    if (node.kind === "variable") {
+      const list = objectLiteralMembers(node, memberLimit + 1);
+      if (list.length > memberLimit) membersCapped = true;
+      const shown = list.slice(0, memberLimit);
+      if (shown.length > 0) detail.members = shown;
     }
     // An enum's members ride on its own node rather than on `contains` edges,
     // because they are not nodes: the outline above finds nothing for an enum
@@ -158,8 +163,10 @@ export function runDetails(
     // kind whose entire content is its member list answered with none of it.
     // Uncapped like every other identity list — the members are the enum.
     if (node.kind === "enum") {
-      const list = enumMembers(node, memberLimit);
-      if (list.length > 0) detail.members = list;
+      const list = enumMembers(node, memberLimit + 1);
+      if (list.length > memberLimit) membersCapped = true;
+      const shown = list.slice(0, memberLimit);
+      if (shown.length > 0) detail.members = shown;
     }
     if (node.literals !== undefined && node.literals.length > 0) {
       detail.literals = node.literals;
@@ -183,6 +190,7 @@ export function runDetails(
     nodes.push(detail);
   }
   return {
+    ...(membersCapped ? { membersCapped: true } : {}),
     result: {
       type: "details",
       nodes,
@@ -224,7 +232,7 @@ function members(
       kind: member.kind,
     };
     if (member.evidence?.startLine) m.line = member.evidence.startLine;
-    const sig = signatureOf(graph.project, member);
+    const sig = signatureOf(graph, member);
     if (sig !== undefined) m.signature = sig;
     const decorators = decoratorsOf(member);
     if (decorators !== undefined) m.decorators = decorators;
@@ -257,83 +265,15 @@ function enumMembers(
 }
 
 function objectLiteralMembers(
-  project: string,
-  span: Pick<ITtscGraphEvidence, "file" | "startLine" | "endLine">,
+  node: ITtscGraphNode,
   limit: number,
 ): ITtscGraphDetails.IMember[] {
-  if (span.endLine === undefined) return [];
-  if (span.endLine - span.startLine > MAX_OBJECT_MEMBER_LINES) return [];
-  const lines = fileLines(project, span.file);
-  if (lines === undefined) return [];
-  const start = Math.max(0, span.startLine - 1);
-  const end = Math.min(lines.length - 1, span.endLine - 1);
-  const members: ITtscGraphDetails.IMember[] = [];
-  let depth = 0;
-  let entered = false;
-  for (let i = start; i <= end; i++) {
-    const raw = lines[i] ?? "";
-    const text = stripStrings(raw);
-    const before = depth;
-    if (entered && before === 1) {
-      const member = objectMemberOf(raw, i + 1);
-      if (member !== undefined) {
-        members.push(member);
-        if (members.length >= limit) break;
-      }
-    }
-    for (const char of text) {
-      if (char === "{") {
-        depth++;
-        entered = true;
-      } else if (char === "}") {
-        depth = Math.max(0, depth - 1);
-      }
-    }
-  }
-  return members;
-}
-
-function objectMemberOf(
-  line: string,
-  lineNumber: number,
-): ITtscGraphDetails.IMember | undefined {
-  const text = line.trim();
-  if (
-    text === "" ||
-    text.startsWith("//") ||
-    text.startsWith("/*") ||
-    text.startsWith("*")
-  ) {
-    return undefined;
-  }
-  const property = /^(['"]?)([A-Za-z_$][\w$-]*)\1\s*\??\s*:/.exec(text);
-  if (property !== null) {
-    return {
-      name: property[2]!,
-      kind: "property",
-      line: lineNumber,
-      signature: signatureLine(text),
-    };
-  }
-  const method =
-    /^(?:async\s+)?(?:get\s+|set\s+)?([A-Za-z_$][\w$-]*)\s*\(/.exec(text);
-  if (method !== null) {
-    return {
-      name: method[1]!,
-      kind: "method",
-      line: lineNumber,
-      signature: signatureLine(text),
-    };
-  }
-  return undefined;
-}
-
-function signatureLine(text: string): string {
-  return text.replace(/\s+/g, " ").replace(/,$/, "");
-}
-
-function stripStrings(line: string): string {
-  return line.replace(/\/\/.*$/, "").replace(/(['"`])(?:\\.|(?!\1).)*\1/g, "");
+  return (node.objectMembers ?? []).slice(0, limit).map((member) => ({
+    name: member.name,
+    kind: member.kind,
+    ...(member.line !== undefined ? { line: member.line } : {}),
+    ...(member.signature !== undefined ? { signature: member.signature } : {}),
+  }));
 }
 
 /** Map dependency edges to references on their far endpoint, dropping structure. */
@@ -461,8 +401,8 @@ function rankedRefs(
 
 /**
  * An identity list's cap: none by default, honored when a caller passes one.
- * details answers a named handle's own shape in full — its members, its values —
- * so the default is unlimited; the tour passes an explicit number to embed a
+ * details answers a named handle's own shape in full — its members, its values
+ * — so the default is unlimited; the tour passes an explicit number to embed a
  * compact slice of its own.
  */
 function limitOf(value: number | undefined): number {
@@ -476,7 +416,11 @@ function limitOf(value: number | undefined): number {
  * uses a symbol grows with its popularity, not with the symbol, so the whole
  * list is a trace/impact answer and details returns an orientation slice.
  */
-function capOf(value: number | undefined, fallback: number, max: number): number {
+function capOf(
+  value: number | undefined,
+  fallback: number,
+  max: number,
+): number {
   const n = value === undefined || !Number.isFinite(value) ? fallback : value;
   return Math.max(1, Math.min(max, Math.floor(n)));
 }
@@ -564,16 +508,6 @@ function evidenceCoordinatesOf(
   };
 }
 
-/** Read a file's lines once, or undefined when it cannot be read. */
-function fileLines(project: string, file: string): string[] | undefined {
-  if (file === "") return undefined;
-  try {
-    return fs.readFileSync(path.join(project, file), "utf8").split(/\r?\n/);
-  } catch {
-    return undefined;
-  }
-}
-
 /**
  * What the declaration says it is: the first sentence of the doc comment
  * written above it.
@@ -587,12 +521,12 @@ function fileLines(project: string, file: string): string[] | undefined {
  * symbol with what it is for is doing an index's job.
  */
 export function docOf(
-  project: string,
+  graph: TtscGraphMemory,
   node: ITtscGraphNode,
 ): string | undefined {
   const evidence = node.evidence;
   const lines =
-    evidence === undefined ? undefined : fileLines(project, evidence.file);
+    evidence === undefined ? undefined : graph.source.lines(evidence.file);
   if (lines === undefined || evidence === undefined) return undefined;
   let index = evidence.startLine - 2;
   while (index >= 0 && (lines[index] ?? "").trim() === "") index--;
@@ -638,12 +572,22 @@ export function docOf(
  * the node.
  */
 export function signatureOf(
-  project: string,
+  graph: TtscGraphMemory,
   node: ITtscGraphNode,
 ): string | undefined {
+  // The producer cuts the head where the compiler says the body opens, so when
+  // it supplied one there is nothing left to infer. The scan below only runs
+  // where it could not: it reads whole physical lines and stops at the first one
+  // holding a `{`, which leaks implementation text when a declaration shares its
+  // line with its body and stops early when the head itself contains a brace.
+  if (node.signature !== undefined && node.signature !== "") {
+    const capped = node.signature.split("\n").slice(0, MAX_SIGNATURE_LINES);
+    const head = capped.join("\n").trim();
+    if (head !== "") return head;
+  }
   const evidence = node.evidence;
   const lines =
-    evidence === undefined ? undefined : fileLines(project, evidence.file);
+    evidence === undefined ? undefined : graph.source.lines(evidence.file);
   if (lines === undefined || evidence === undefined) return undefined;
   const start = Math.max(0, evidence.startLine - 1);
   const last =

package/src/server/runEntrypoints.ts

@@ -118,7 +118,7 @@ function nodeOf(
   };
   if (node.evidence?.startLine !== undefined)
     out.line = node.evidence.startLine;
-  const signature = signatureOf(graph.project, node);
+  const signature = signatureOf(graph, node);
   if (signature !== undefined) out.signature = signature;
   const decorators = decoratorsOf(node);
   if (decorators !== undefined) out.decorators = decorators;

package/src/server/runLookup.ts

@@ -88,7 +88,7 @@ export function runLookup(
   for (const hit of hits) {
     const node = graph.node(hit.id);
     if (node === undefined) continue;
-    const sig = signatureOf(graph.project, node);
+    const sig = signatureOf(graph, node);
     if (sig !== undefined) hit.signature = sig;
   }
   return {