@ttsc/graph 0.19.2 → 0.19.3

package/src/server/resultAudit.ts

@@ -47,14 +47,18 @@
  * payload, and told it to stop where the shortlist's coverage was exactly what
  * needed judging.
  *
- * So there are two audits. {@link RESULT_AUDIT} covers the operations that walk
- * from an explicit handle or structure (`trace`, `details`, `overview`): the
- * result is what the graph holds for what you named, bounded only where
- * `truncated` says. {@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
@@ -104,6 +108,41 @@ span is a sound next step, not a failure to trust the result.
 Follow \`next\` for where that leaves the question.
 `.trim();
 
+/**
+ * The audit for `details`, whose contract is not the other exact operations'.
+ *
+ * `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
+ * 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
+ * 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
+ * the audit has to say which half is which so the reader trusts the complete
+ * one and reaches for `trace` on the other, instead of reading the file for a
+ * member list that is already here.
+ */
+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.
+
+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
+what is already here. What a symbol reaches or is reached by — its calls, its type
+references, its implementers, and under \`neighbors\` its dependents — is a short orientation
+slice, not the whole set, because that grows with how widely a symbol is used; \`trace\`
+follows it in full.
+
+Follow \`next\`: answer from this result, and re-call the graph only when it says inspect, or
+after you edit the source.
+`.trim();
+
 /** 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/runDetails.ts

@@ -15,17 +15,20 @@ 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;
-// Neighbor lists are a map, not a dump; keep them scannable.
+// 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
+// tokens of "who uses this", which is a trace/impact question, not "what is
+// this". So fan-out is a small default slice; identity (members, literals) is
+// not, because a class's members and a union's values are the symbol itself and
+// are bounded by the declaration.
 const DEFAULT_NEIGHBORS = 2;
 const MAX_NEIGHBORS = 3;
-// A container outline can be long; default to a scannable first page.
-const DEFAULT_MEMBERS = 6;
-const MAX_MEMBERS = 8;
-// Direct dependency groups are orientation slices, not full fan-out dumps.
 const DEFAULT_DEPENDENCIES = 2;
 const MAX_DEPENDENCIES = 4;
-// Object literal outlines are navigation aids, not source excerpts.
-const MAX_OBJECT_MEMBER_LINES = 300;
 // Structural relationships are navigation, not the dependency picture details is for.
 const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
 // Kinds whose value is their member outline, not implementation text.
@@ -47,17 +50,17 @@ export function runDetails(
   graph: TtscGraphMemory,
   props: ITtscGraphDetails.IRequest,
 ): IRunnerOutput<ITtscGraphDetails> {
-  const neighborLimit = bound(
-    props.neighborLimit,
-    DEFAULT_NEIGHBORS,
-    1,
-    MAX_NEIGHBORS,
-  );
-  const memberLimit = bound(props.memberLimit, DEFAULT_MEMBERS, 1, MAX_MEMBERS);
-  const dependencyLimit = bound(
+  // Identity is the whole answer. The caller named this handle to learn what it
+  // is, and a class's members or a union's values are the symbol itself — cut
+  // them and the model reads the file for the rest, the read this index exists
+  // to remove. So `memberLimit` and `literals` default to unlimited. Fan-out
+  // 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);
+  const dependencyLimit = capOf(
     props.dependencyLimit,
     DEFAULT_DEPENDENCIES,
-    1,
     MAX_DEPENDENCIES,
   );
   const wantNeighbors = props.neighbors === true;
@@ -101,7 +104,6 @@ export function runDetails(
     if (sig !== undefined) detail.signature = sig;
     const doc = docOf(graph.project, node);
     if (doc !== undefined) detail.doc = doc;
-    const signatureLiterals = literalSummaries(sig);
     const decorators = decoratorsOf(node);
     if (decorators !== undefined) detail.decorators = decorators;
     const implementation = evidenceCoordinatesOf(node.implementation);
@@ -150,8 +152,18 @@ export function runDetails(
       );
       if (list.length > 0) detail.members = list;
     }
-    if (signatureLiterals.length > 0)
-      detail.literals = signatureLiterals.slice(0, 6);
+    // 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
+    // and always did. Its signature stops at the `{`, so without this the one
+    // 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;
+    }
+    if (node.literals !== undefined && node.literals.length > 0) {
+      detail.literals = node.literals;
+    }
     if (wantNeighbors) {
       detail.dependsOn = refs(
         graph,
@@ -222,6 +234,28 @@ function members(
   return out;
 }
 
+/**
+ * An enum's members, owner-qualified so the name reads the way the code writes
+ * it, with the value each carries as its signature.
+ *
+ * The name is why this exists. `literals` answers what values the enum admits,
+ * but a caller writes `Colors.Red` and never `"red"`, so an enum the graph
+ * already held sent a caller that had named it to the file for the one fact it
+ * came for (#738).
+ */
+function enumMembers(
+  node: ITtscGraphNode,
+  limit: number,
+): ITtscGraphDetails.IMember[] {
+  return (node.enumMembers ?? []).slice(0, limit).map((member) => ({
+    name: `${node.qualifiedName ?? node.name}.${member.name}`,
+    kind: "property",
+    ...(member.value !== undefined
+      ? { signature: `${member.name} = ${member.value}` }
+      : {}),
+  }));
+}
+
 function objectLiteralMembers(
   project: string,
   span: Pick<ITtscGraphEvidence, "file" | "startLine" | "endLine">,
@@ -328,13 +362,11 @@ function refs(
     if (evidence !== undefined) ref.evidence = evidence;
     ranked.push({ ref, rank: refRank(ref, edge) });
   }
+  // Ranked so a caller that does throttle (the tour) keeps the strongest refs,
+  // not the ones nearest the top of a file. Uncapped, `limit` is Infinity and
+  // the sort is just a stable order.
   ranked.sort((a, b) => a.rank - b.rank);
-  const out: ITtscGraphDetails.IReference[] = [];
-  for (const item of ranked) {
-    out.push(item.ref);
-    if (out.length >= limit) break;
-  }
-  return out;
+  return ranked.map((item) => item.ref).slice(0, limit);
 }
 
 const executionKinds = new Set([
@@ -375,17 +407,7 @@ function dependencyRefs(
       rank: refRank(ref, edge),
     });
   }
-  ranked.sort((a, b) => a.rank - b.rank);
-  const out: ITtscGraphDetails.IReference[] = [];
-  const seen = new Set<string>();
-  for (const item of ranked) {
-    const key = `${item.ref.relation}:${item.ref.id}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
-    out.push(item.ref);
-    if (out.length >= limit) break;
-  }
-  return out;
+  return rankedRefs(ranked, limit);
 }
 
 function incomingDependencyRefs(
@@ -416,6 +438,14 @@ function incomingDependencyRefs(
       rank: refRank(ref, edge),
     });
   }
+  return rankedRefs(ranked, limit);
+}
+
+/** Sort by rank, drop duplicate (relation, id) pairs, and cut to `limit`. */
+function rankedRefs(
+  ranked: Array<{ ref: ITtscGraphDetails.IReference; rank: number }>,
+  limit: number,
+): ITtscGraphDetails.IReference[] {
   ranked.sort((a, b) => a.rank - b.rank);
   const out: ITtscGraphDetails.IReference[] = [];
   const seen = new Set<string>();
@@ -429,38 +459,26 @@ function incomingDependencyRefs(
   return out;
 }
 
-function literalSummaries(text: string | undefined): string[] {
-  if (text === undefined) return [];
-  const out: string[] = [];
-  for (const match of text.matchAll(/(["'`])((?:\\.|(?!\1).){1,80})\1/g)) {
-    const value = cleanLiteral(match[2]);
-    if (value !== undefined && !out.includes(value)) out.push(value);
-    if (out.length >= 20) break;
-  }
-  return out;
-}
-
-function cleanLiteral(value: string | undefined): string | undefined {
-  const text = value?.replace(/\s+/g, " ").trim();
-  if (
-    text === undefined ||
-    text === "" ||
-    text.length > 40 ||
-    /^[{}()[\],.:;]+$/.test(text)
-  ) {
-    return undefined;
-  }
-  return text;
+/**
+ * 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
+ * compact slice of its own.
+ */
+function limitOf(value: number | undefined): number {
+  return value === undefined || !Number.isFinite(value)
+    ? Infinity
+    : Math.max(1, Math.floor(value));
 }
 
-function bound(
-  value: number | undefined,
-  fallback: number,
-  min: number,
-  max: number,
-): number {
+/**
+ * A fan-out list's cap: a small default, clamped to a ceiling. What names or
+ * 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 {
   const n = value === undefined || !Number.isFinite(value) ? fallback : value;
-  return Math.max(min, Math.min(max, Math.floor(n)));
+  return Math.max(1, Math.min(max, Math.floor(n)));
 }
 
 /**
@@ -611,6 +629,13 @@ export function docOf(
  * The declaration signature: the head of the declaration up to and including
  * the line that opens its body (`{`), or the single declaration line when there
  * is no brace, capped so a wrapped signature cannot run away.
+ *
+ * It never runs past the declaration's own span. The stop used to be the brace,
+ * the trailing semicolon, or the line cap, and a declaration ending in none of
+ * them read its neighbors instead: an enum member ends in a comma, so `VIEW`
+ * came back as itself plus the two members after it and the closing brace. The
+ * span is the fact that says where the declaration ends, and it was already on
+ * the node.
  */
 export function signatureOf(
   project: string,
@@ -621,12 +646,12 @@ export function signatureOf(
     evidence === undefined ? undefined : fileLines(project, evidence.file);
   if (lines === undefined || evidence === undefined) return undefined;
   const start = Math.max(0, evidence.startLine - 1);
+  const last =
+    evidence.endLine === undefined
+      ? lines.length - 1
+      : Math.min(lines.length - 1, evidence.endLine - 1);
   const out: string[] = [];
-  for (
-    let i = start;
-    i < lines.length && out.length < MAX_SIGNATURE_LINES;
-    i++
-  ) {
+  for (let i = start; i <= last && out.length < MAX_SIGNATURE_LINES; i++) {
     const line = lines[i];
     if (line === undefined) break;
     out.push(line);

package/src/structures/ITtscGraphApplication.ts

@@ -169,13 +169,14 @@ export namespace ITtscGraphApplication {
      * resolves to the type-checked program for the snapshot the call synced to,
      * so opening a file it cites only returns a fact already in it.
      *
-     * The audit is operation-aware. For the exact operations (`trace`,
-     * `details`, `overview`) it reports the result as the structure the graph
-     * holds for the handles named, bounded only where `truncated` says. For the
-     * ranked operations (`lookup`, `entrypoints`, `tour`) it adds that the
-     * selection is heuristic — matched, scored, ranked, and limited against the
-     * question — so the facts are verified but the shortlist's coverage is the
-     * caller's to judge.
+     * The audit is operation-aware. For the walks from a named handle (`trace`,
+     * `overview`) it reports the result as the structure the graph holds,
+     * bounded where `truncated` says. For `details` it reports the two halves of
+     * a resolved symbol: its own shape returned whole, its fan-out returned as a
+     * slice with `trace` for the rest. For the ranked operations (`lookup`,
+     * `entrypoints`, `tour`) it adds that the selection is heuristic — matched,
+     * scored, ranked, and limited against the question — so the facts are
+     * verified but the shortlist's coverage is the caller's to judge.
      */
     audit: string;
 

package/src/structures/ITtscGraphDetails.ts

@@ -49,24 +49,26 @@ export namespace ITtscGraphDetails {
     neighbors?: boolean;
 
     /**
-     * Maximum dependencies and dependents per side when `neighbors:true`. Above
-     * a few is usually overfetch; call `trace` for flow instead.
+     * Dependencies and dependents per side when `neighbors:true`. A small
+     * orientation slice by default; what uses a symbol grows with its
+     * popularity, so `trace` answers the whole "who uses this".
      *
      * @default 2
      */
     neighborLimit?: number;
 
     /**
-     * Maximum owned members for a container or object literal.
-     *
-     * @default 6
+     * Owned members for a container or object literal. The complete outline by
+     * default — a class's members and an enum's are the symbol itself, so they
+     * are not sampled. Pass a number to cap.
      */
     memberLimit?: number;
 
     /**
-     * Maximum direct execution and type references per group.
+     * Direct execution and type references per group. A small orientation slice
+     * by default; `trace` follows the whole fan-out.
      *
-     * @default 1
+     * @default 2
      */
     dependencyLimit?: number;
 
@@ -145,7 +147,15 @@ export namespace ITtscGraphDetails {
     /** Concrete nodes that implement or override this interface/base member. */
     implementedBy?: IReference[];
 
-    /** String literal values from the signature. */
+    /**
+     * The complete value set a type alias or enum admits, in TypeScript source
+     * form (`"a"`, `1`, `true`, `null`) — the checker's resolved union members,
+     * not the quoted tokens that happened to fit in `signature`.
+     *
+     * Absent when the type has no enumerable value set. A `signature` is capped
+     * at the declaration head, so for a union or enum written across several
+     * lines this is the field that carries the members.
+     */
     literals?: string[];
 
     /**

package/src/structures/ITtscGraphNode.ts

@@ -63,6 +63,32 @@ export interface ITtscGraphNode {
   /** Declaration modifiers, when the declaration pass recorded any. */
   modifiers?: TtscGraphNodeModifier[];
 
+  /**
+   * The complete value set of a type alias or enum whose declared type the
+   * checker resolved to literals, each in TypeScript source form (`"a"`, `1`,
+   * `true`, `null`).
+   *
+   * Present only when every constituent is enumerable, so the list is the whole
+   * type and never a sample of it: `type T = Kind | string` admits values no
+   * list can name and carries none. It is resolved from the type, not read off
+   * the declaration, so indirection (`type I = Kind | 'f'`) is followed and the
+   * answer does not depend on how the declaration is wrapped.
+   */
+  literals?: string[];
+
+  /**
+   * What an enum declares, in checker order: the name a caller writes and the
+   * value it carries. Absent on every other kind.
+   *
+   * `literals` says which values the enum admits, which is what a serializer
+   * asks. The code says `Colors.Red`, so the names are the other half, and
+   * without them a caller that had already named the enum still had to open the
+   * file to learn what to type. The members are not nodes — `Colors.Red` is a
+   * string a grep finds exactly — so this fills in the node the graph already
+   * holds instead of minting one per member.
+   */
+  enumMembers?: ITtscGraphNode.IEnumMember[];
+
   /**
    * Decorators written on this declaration, in source order: raw facts
    * (`@Controller`, `@Get`) a consumer interprets without re-parsing source.
@@ -78,3 +104,17 @@ export interface ITtscGraphNode {
    */
   implementation?: ITtscGraphEvidence;
 }
+export namespace ITtscGraphNode {
+  /** One member of an enum: the name a caller writes and the value it carries. */
+  export interface IEnumMember {
+    /** The member's own name, unqualified (`Red` on `Colors.Red`). */
+    name: string;
+
+    /**
+     * The value it carries, in TypeScript source form (`"red"`, `1`). Absent
+     * for a computed member the checker could not fold to a constant; the name
+     * still stands.
+     */
+    value?: string;
+  }
+}

package/src/structures/ITtscGraphTour.ts

@@ -66,7 +66,7 @@ export namespace ITtscGraphTour {
      * Central entrypoints to seed the tour. Raise only when the question names
      * several public paths that must all appear in one answer.
      *
-     * @default 4
+     * @default 5
      */
     limit?: number;