@ttsc/graph 0.19.1 → 0.19.2

package/src/structures/ITtscGraphDump.ts

@@ -7,13 +7,19 @@ import { ITtscGraphSpan } from "./ITtscGraphSpan";
  * wire contract between the Go fact-builder and the TypeScript graph engine.
  *
  * It is the complete graph with none of the per-response caps the MCP tools
- * apply: every node and edge the build resolved. The server parses each changed
- * native snapshot (typia-validated) into an in-memory resident graph and reuses
- * that warm model while project inputs stay unchanged; the bundled 3D viewer
- * reduces the same dump.
+ * apply: every node and edge the build resolved, plus the `provenance` that
+ * says which program resolved them. The server parses each changed native
+ * snapshot (typia-validated) into an in-memory resident graph and reuses that
+ * warm model while project inputs stay unchanged; the bundled 3D viewer reduces
+ * the same dump.
  *
- * Paths in `project` and `tsconfig` are absolute; `file` fields on nodes and
- * edges are project-relative.
+ * `project` is absolute. Every other path is relative to it — `tsconfig`, and
+ * the `file` fields on nodes, edges, diagnostics, and the provenance manifest.
+ *
+ * Two kinds of path fall outside the project and so cannot be relative to it: a
+ * dependency keeps its `node_modules/`-relative tail, which is what makes a
+ * dependency leaf readable, and anything else the compiler loaded keeps the
+ * identity the compiler gave it — a virtual lib stays `bundled:///…`.
  */
 export interface ITtscGraphDump {
   /** Absolute path of the project root the graph was built for. */
@@ -22,6 +28,17 @@ export interface ITtscGraphDump {
   /** The tsconfig the program was loaded from, relative to `project`. */
   tsconfig: string;
 
+  /** Evidence about the one program that produced everything below. */
+  provenance: ITtscGraphDump.IProvenance;
+
+  /**
+   * The compiler's findings for the same generation that produced the facts.
+   *
+   * Empty means the program reported none. It does not mean they were not
+   * collected — `provenance.capabilities` is what says whether they were.
+   */
+  diagnostics: ITtscGraphDump.IDiagnostic[];
+
   /** Every node the build recorded. */
   nodes: ITtscGraphDump.INode[];
 
@@ -30,6 +47,177 @@ export interface ITtscGraphDump {
 }
 
 export namespace ITtscGraphDump {
+  /**
+   * What a snapshot knows about its own origin.
+   *
+   * The graph's claim is that its nodes, edges, spans, and diagnostics all came
+   * from one `Program`. Without this the claim is unprovable from the response:
+   * a consumer could only re-read the disk afterwards and hope nothing moved,
+   * which is not sound — a write that lands and reverts in between is invisible
+   * to it, and a re-read proves what the disk says now, never what the checker
+   * resolved against.
+   *
+   * This carries no source text. A digest is the opposite of inlining: it is
+   * what lets a consumer prove byte-identity against text it read itself,
+   * without the graph ever shipping that text.
+   */
+  export interface IProvenance {
+    /**
+     * The dump body's schema version, moved when a field is added, removed, or
+     * redefined. Independent of the serve protocol's version: a dump written to
+     * a file has a schema but never rode the protocol.
+     */
+    schemaVersion: number;
+
+    /**
+     * What this snapshot proves. A consumer degrades against this rather than
+     * guessing from a field's emptiness, because an empty list and an
+     * uncollected one look identical on the wire.
+     *
+     * The known members are `universe`, `sourceDigests`, `diskDigests`, and
+     * `diagnostics`. The type stays `string[]` rather than a union of those on
+     * purpose: a union would make `typia.assert` reject a newer producer for
+     * naming a capability this client has not heard of, turning "proves more
+     * than you know about" into a hard failure. An unknown capability is
+     * exactly the case a consumer should ignore.
+     */
+    capabilities: string[];
+
+    /** What built the snapshot. */
+    producer: IProducer;
+
+    /** The inputs that decide which files are in the program at all. */
+    universe: IUniverse;
+
+    /** One entry per file the program loaded, ordered by file. */
+    sources: ISourceDigest[];
+  }
+
+  /**
+   * Identifies the binary and the checker behind the facts.
+   *
+   * `tool` and `version` are separate because more than one binary can produce
+   * a dump and they do not share a version line — the shipped `ttscgraph` is
+   * stamped at release, the internal viewer tool is not versioned at all — so
+   * folding the name in would hand a consumer that parses a version a tool
+   * name.
+   */
+  export interface IProducer {
+    /** The producing binary's name, such as `ttscgraph`. */
+    tool: string;
+
+    /**
+     * The producing binary's build version, as its `--version` prints it. A
+     * local build reports the dev placeholder; a tool that carries no version
+     * reports `""`.
+     */
+    version: string;
+
+    /** The TypeScript version typescript-go implements. */
+    typescript: string;
+  }
+
+  /**
+   * The build universe: the inputs that decide which files the program
+   * contains, as opposed to what is inside them. A change to any of them can
+   * add or drop whole files, so a consumer reusing facts across snapshots must
+   * treat a universe change as invalidating everything.
+   */
+  export interface IUniverse {
+    /**
+     * The tsconfig chain — the project's config and everything it extends.
+     *
+     * It stays an input regardless of what any source contains: compiler
+     * options change the meaning of code the checker resolves without any
+     * source file changing.
+     */
+    configs: IFileDigest[];
+
+    /**
+     * The resolved root file set, one entry per (config, file) pair. A root a
+     * config names but that does not exist is still listed: its absence is part
+     * of the fingerprint, and creating it later changes the program.
+     */
+    roots: IRootFile[];
+  }
+
+  /** A root file attributed to the config that named it. */
+  export interface IRootFile {
+    /** The tsconfig that named this root, project-relative. */
+    config: string;
+
+    /** The root file, project-relative. */
+    file: string;
+  }
+
+  /** A file and the hex-encoded SHA-256 of its on-disk bytes. */
+  export interface IFileDigest {
+    /** Project-relative. */
+    file: string;
+
+    /** Hex-encoded SHA-256. */
+    digest: string;
+  }
+
+  /**
+   * The manifest entry for one source file the program loaded.
+   *
+   * Two digests, because "the bytes the checker read" and "the bytes on disk"
+   * are not always the same string and a consumer needs to know which one it
+   * compares against. They diverge when a source-preamble plugin injects text
+   * ahead of the file before tsgo parses it, which a real plugin project does
+   * on every build.
+   */
+  export interface ISourceDigest {
+    /** Project-relative. */
+    file: string;
+
+    /**
+     * Hex-encoded SHA-256 of the text the checker resolved against — the ground
+     * truth for the facts. Every node, edge, and span attributed to this file
+     * was computed from these bytes.
+     */
+    checkerDigest: string;
+
+    /**
+     * Hex-encoded SHA-256 of the file's on-disk bytes at snapshot time, or `""`
+     * when it could not be read: it vanished mid-load, or it is a virtual
+     * source with no on-disk identity.
+     *
+     * This is the one a consumer that opens the file itself can reproduce. When
+     * it equals `checkerDigest`, a matching read proves byte-identity with the
+     * facts. When it does not, the checker saw augmented text and that proof is
+     * simply not available for this file — which is a thing to report, not to
+     * paper over.
+     *
+     * Read it only when `provenance.capabilities` lists `diskDigests`. Without
+     * that claim every one of these is empty because the producer never hashed
+     * the disk, which is a different fact from a file that could not be read.
+     */
+    diskDigest: string;
+  }
+
+  /** One compiler diagnostic from the generation that produced the facts. */
+  export interface IDiagnostic {
+    /** Project-relative. */
+    file: string;
+
+    /** 1-based line. */
+    line: number;
+
+    /** 1-based column. */
+    column: number;
+
+    /** The TypeScript diagnostic code, such as 2322. */
+    code: number;
+
+    /** Whether the finding fails a build. */
+    category: "error" | "warning";
+
+    /** The diagnostic text, without the code prefix. */
+    message: string;
+  }
+
   /**
    * A node as the builder sends it: the graph node, minus the file paths inside
    * its spans, which the loader puts back from the node's own `file`.

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/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";