@ttsc/graph 0.19.1 → 0.19.3

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/ITtscGraphSnapshot.ts

@@ -0,0 +1,69 @@
+import { ITtscGraphDump } from "./ITtscGraphDump";
+
+/**
+ * One response frame of the `ttscgraph serve` protocol.
+ *
+ * This is the envelope around a snapshot, mirrored by hand from `serveResponse`
+ * in `packages/ttsc/cmd/ttscgraph/serve.go`. There is no generator between the
+ * Go struct and this interface, so the two drift silently unless something
+ * checks them; `TtscGraphSession` validates every frame against this shape
+ * rather than casting it, so a drift surfaces as a precise error on the first
+ * frame instead of an `undefined` several layers downstream.
+ */
+export interface ITtscGraphSnapshot {
+  /** Echoes the request's id, so a response finds its caller. */
+  id: number;
+
+  /**
+   * The protocol version the server speaks.
+   *
+   * It rides every frame rather than a handshake. The binary and this package
+   * version independently — the session runs whichever `ttscgraph` the target
+   * project installed, or whatever `TTSC_GRAPH_BINARY` points at — so a
+   * mismatched pair is reachable, and before this field nothing detected it:
+   * the first symptom was a misparsed dump or a silently absent value.
+   */
+  protocolVersion: number;
+
+  /**
+   * What the producer did to answer this request.
+   *
+   * Required, and never absent — including on the error path, where it is
+   * `"error"`. A consumer can report `rebuild` versus `incremental` honestly
+   * because the compiler said so; no generation counter can distinguish a reuse
+   * from a full rebuild after the fact.
+   */
+  mode: ITtscGraphSnapshot.Mode;
+
+  /** What this server can prove about the snapshots it publishes. */
+  capabilities: string[];
+
+  /** Whether the graph moved since the last snapshot. */
+  changed: boolean;
+
+  /** The snapshot, present exactly when `changed` is true. */
+  dump?: ITtscGraphDump;
+
+  /** Set when the request produced no snapshot; `mode` is then `"error"`. */
+  error?: string;
+}
+
+export namespace ITtscGraphSnapshot {
+  /**
+   * The computation modes the producer reports, plus the transport's `error`.
+   *
+   * - `initial`: the session's first snapshot.
+   * - `reload`: the build universe moved, so the program was reloaded whole.
+   * - `unchanged`: nothing moved; no dump rides it and the last one still holds.
+   * - `incremental`: edits applied onto the reused resident program.
+   * - `rebuild`: edits applied, but the program could not be reused.
+   * - `error`: no snapshot was produced.
+   */
+  export type Mode =
+    | "initial"
+    | "reload"
+    | "unchanged"
+    | "incremental"
+    | "rebuild"
+    | "error";
+}

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;
 

package/src/structures/index.ts

@@ -17,6 +17,7 @@ export * from "./ITtscGraphOverview";
 export * from "./ITtscGraphLookup";
 export * from "./ITtscGraphNext";
 export * from "./ITtscGraphTrace";
+export * from "./ITtscGraphSnapshot";
 export * from "./ITtscGraphSpan";
 export * from "./ITtscGraphTour";
 export * from "./TtscGraphEdgeKind";