ttsc 0.26.2 → 0.28.0

package/cmd/ttscgraph/serve.go

@@ -57,27 +57,82 @@ const (
 )
 
 // fullSnapshotCapabilities is what a snapshot from a resident compiler session
-// proves. Both commands that own a real Program declare all three; the constant
-// exists so the envelope's claim and the dump's claim cannot drift apart.
+// proves. Both commands that own a real Program declare every one of them; the
+// constant exists so the envelope's claim and the dump's claim cannot drift
+// apart.
 var fullSnapshotCapabilities = []string{
   graph.CapabilityUniverse,
   graph.CapabilitySourceDigests,
   graph.CapabilityDiskDigests,
   graph.CapabilityDiagnostics,
+  graph.CapabilityDocTags,
 }
 
-// serveCapabilities is what this server can prove, answered before a consumer
-// has a dump to inspect — an `unchanged` response carries no dump, and a client
-// negotiating on the first frame has not parsed one yet. It mirrors what every
-// dump this server publishes declares for itself.
+// serveCapabilities is what this server can prove before a session exists —
+// the frame a client reads when the project could not even be loaded. Once a
+// session exists its own capabilities answer, because those depend on what a
+// plugin published and this list cannot know it.
 var serveCapabilities = fullSnapshotCapabilities
 
+// capabilities is what THIS session proves, which is the shared list plus the
+// artifact claim when a plugin published one.
+//
+// The claim has to be conditional for the same reason it is on the dump command:
+// a project that publishes no artifacts and a session that was never handed any
+// are the same absent nodes, and only the claim separates them.
+func (s *graphSession) capabilities() []string {
+  if len(s.artifacts) == 0 {
+    return fullSnapshotCapabilities
+  }
+  return append(
+    append([]string{}, fullSnapshotCapabilities...),
+    graph.CapabilityArtifactNodes,
+  )
+}
+
+// artifactProducer names the second producer behind this session's artifact
+// nodes, and is nil when it has none.
+// provenance is this session's published origin for one generation.
+func (s *graphSession) provenance(texts map[string]string) graph.Provenance {
+  built := graph.NewProvenance(
+    serveProducer(),
+    s.capabilities(),
+    s.configDigests,
+    s.roots,
+    texts,
+    s.diskDigests,
+  )
+  built.ArtifactProducer = s.artifactProducer()
+  return built
+}
+
+func (s *graphSession) artifactProducer() *graph.Producer {
+  if len(s.artifacts) == 0 {
+    return nil
+  }
+  return &graph.Producer{Tool: "@ttsc/lint graph-nodes"}
+}
+
 type serveRequest struct {
   ID int `json:"id"`
   // GraphSnapshotVersion opts into the incremental shard protocol. Omitted
-  // requests retain the schema-v6 full-dump response for existing
-  // @ttsc/graph clients.
+  // requests retain the full-dump response for existing @ttsc/graph clients.
   GraphSnapshotVersion int `json:"graphSnapshotVersion,omitempty"`
+  // Artifacts is the path to the set a plugin published for this request, which
+  // the client re-derives when the documents or lint configuration behind it
+  // moved. It rides every request rather than only the changed ones: the client
+  // is the only side that can see those inputs, and the server is the only side
+  // that knows what it last applied, so the honest exchange is the client
+  // stating what it currently has and the server comparing it with its own.
+  //
+  // Three states, which is why it is a pointer. Absent is a client with no
+  // opinion — one predating this field, or one driving a session through the
+  // startup flag — and the set already applied stands. Empty is a client
+  // stating it now has none, which withdraws that set: a project whose
+  // publisher was removed must stop being answered with its artifacts, and
+  // without a way to say so it would be answered with them until the editor
+  // restarted. A path is the set to apply.
+  Artifacts *string `json:"artifacts,omitempty"`
 }
 
 type serveResponse struct {
@@ -119,8 +174,30 @@ func errorResponse(id int, message string) serveResponse {
 }
 
 type graphSession struct {
-  cwd          string
-  tsconfig     string
+  cwd      string
+  tsconfig string
+  // artifacts is the set a plugin published: a second producer's facts about
+  // documents this Program never read. Refreshing it is therefore not a refresh
+  // of the graph — editing a Markdown heading moves the artifact and not one
+  // compiler fact — so the two invalidations stay separate questions, and this
+  // one is answered by adoptArtifacts rather than by the build universe.
+  artifacts []graph.Artifact
+  // artifactsDigest is the content of the set currently applied. Content, and
+  // not the path or its modification time: the client overwrites one file per
+  // process and project, so the path never moves for a given session, and a
+  // republish triggered by a document whose headings did not actually change
+  // writes the same bytes and must therefore cost nothing.
+  artifactsDigest [sha256.Size]byte
+  // artifactsFile and artifactsStat are what the digest was taken from, kept so
+  // an unchanged file need not be read at all. The set is one entry per
+  // document section, model field, and operation, so it is bounded by the
+  // project's documentation rather than by anything small — and this comparison
+  // runs before every graph request, where reading and hashing that whole file
+  // to learn it did not move is the kind of cost a resident session pays
+  // forever.
+  artifactsFile string
+  artifactsStat artifactsFileState
+
   compiler     *driver.Session
   configHashes map[string][sha256.Size]byte
   auxStates    map[string]diskState
@@ -140,21 +217,134 @@ type graphSession struct {
   graphStore              *serveGraphStore
   requestProtocol         int
   requestProtocolSelected bool
-  // pending remembers a generation whose state was captured but whose selected
-  // projection failed. Until an input change lets the session rebuild, an
-  // unchanged request retries the same full or partial invalidation instead of
-  // falsely confirming the older client graph.
+  // pending remembers work the next request owes regardless of what the build
+  // universe says: a generation whose state was captured but whose selected
+  // projection failed, or an artifact set adopted after the graph carrying the
+  // previous one was built. Until it is discharged, an otherwise unchanged
+  // request retries the recorded invalidation instead of falsely confirming the
+  // older client graph.
   pending *graphChange
 }
 
 func newGraphSession(cwd, tsconfig string) (*graphSession, error) {
-  session := &graphSession{cwd: cwd, tsconfig: tsconfig}
+  return newGraphSessionWithArtifacts(cwd, tsconfig, nil)
+}
+
+// newGraphSessionWithArtifacts is the constructor the serve command uses, and
+// the plain one above is it with nothing published. The artifacts are read once
+// and held for the session: they are a second producer's facts about documents
+// this Program never read, so refreshing them is a different question from
+// refreshing the graph, and only the first answer is wired today.
+func newGraphSessionWithArtifacts(
+  cwd, tsconfig string,
+  artifacts []graph.Artifact,
+) (*graphSession, error) {
+  session := &graphSession{cwd: cwd, tsconfig: tsconfig, artifacts: artifacts}
   if err := session.reload(); err != nil {
     return nil, err
   }
   return session, nil
 }
 
+// adoptArtifacts makes what the request states the set this session applies,
+// and reports whether that replaced a set some already-built graph carries.
+//
+// A nil statement is a client with no opinion, and the set already applied
+// stands: dropping it on the say-so of a client that never mentioned artifacts
+// would delete them from the graph of every session driven through the startup
+// flag alone.
+//
+// A read failure is returned rather than swallowed. The client wrote this file
+// moments ago and named it in the same request, so a file that cannot be read
+// is a broken exchange, not a project without artifacts — and answering with a
+// silently artifact-free graph would look exactly like a correct answer.
+func (s *graphSession) adoptArtifacts(named *string) (bool, error) {
+  if named == nil {
+    return false, nil
+  }
+  path := strings.TrimSpace(*named)
+  if path == "" {
+    return s.applyArtifacts(nil, withdrawnArtifactsDigest), nil
+  }
+  stat, err := os.Stat(path)
+  if err != nil {
+    return false, err
+  }
+  state := artifactsFileState{size: stat.Size(), modTime: stat.ModTime().UnixNano()}
+  if path == s.artifactsFile && state == s.artifactsStat {
+    return false, nil
+  }
+  // One read, hashed and decoded from the same bytes. Reading twice would let
+  // an overwrite land between them and leave this session recording an identity
+  // for a set it is not holding — after which a later request naming the file
+  // it recorded would be answered as unchanged.
+  contents, err := os.ReadFile(path)
+  if err != nil {
+    return false, err
+  }
+  next, err := graph.ParseArtifacts(contents)
+  if err != nil {
+    return false, err
+  }
+  s.artifactsFile = path
+  s.artifactsStat = state
+  return s.applyArtifacts(next, sha256.Sum256(contents)), nil
+}
+
+// artifactsFileState is what an unchanged published file looks like from the
+// outside: size and modification time, never contents. It exists only to decide
+// whether the file is worth reading, and the digest taken from those contents is
+// still what decides whether the set is worth applying.
+type artifactsFileState struct {
+  size int64
+  // modTime is nanoseconds since the epoch rather than a time.Time, so the
+  // struct compares with == and means it. A time.Time carries a location
+  // pointer and an optional monotonic reading, and comparing two of those with
+  // == is a well-known way to get a false inequality that reads as a changed
+  // file forever.
+  modTime int64
+}
+
+// applyArtifacts installs a set and reports whether it differs from the applied
+// one. The first application of a session reports a change like any other and
+// costs nothing: no graph has been projected yet, so the invalidation it
+// records is discharged by the initial projection that was going to happen
+// regardless.
+func (s *graphSession) applyArtifacts(next []graph.Artifact, digest [sha256.Size]byte) bool {
+  if digest == s.artifactsDigest {
+    return false
+  }
+  s.artifacts = next
+  s.artifactsDigest = digest
+  return true
+}
+
+// withdrawnArtifactsDigest stands for "the client states it has none".
+//
+// A constant rather than the hash of an empty file, so that the withdrawn state
+// and a file whose contents happen to hash to the same value cannot be confused
+// — and domain-separated so it is not the digest of anything a producer writes.
+var withdrawnArtifactsDigest = sha256.Sum256([]byte("ttscgraph:artifacts:none"))
+
+// invalidateArtifacts records that the next projection must be a full one.
+//
+// Full, because replacing the published set is not a per-file delta: it moves
+// the artifact nodes and every citation edge into them at once, and the
+// incremental path is built to answer a different question — which sources
+// changed. It happens to reach the same answer here, through the closure
+// expansion that pulls a citing source back in, but that is a property of
+// machinery aimed elsewhere and not a guarantee this depends on.
+//
+// Full, but not a reload: the Program is reused untouched, because no compiler
+// input moved. That is the whole point of keeping documents out of the build
+// universe — a Markdown edit costs one projection, never one typecheck.
+func (s *graphSession) invalidateArtifacts() {
+  if s.pending != nil && s.pending.full {
+    return
+  }
+  s.pending = &graphChange{mode: serveModeRebuild, full: true}
+}
+
 func (s *graphSession) Close() error {
   if s.compiler == nil {
     return nil
@@ -385,9 +575,11 @@ func (s *graphSession) captureState() error {
     return err
   }
   inputs := auxiliaryInputs(program, configs, s.cwd)
-  inputs = append(inputs, missingRootInputs(configs, sourceHashes)...)
+  for _, path := range missingRootInputs(configs, sourceHashes) {
+    inputs = append(inputs, auxiliaryInput{path: path})
+  }
   s.configHashes = configHashes
-  s.auxStates = captureDiskStates(compactSortedStrings(inputs))
+  s.auxStates = captureDiskStates(compactAuxiliaryInputs(inputs))
   s.sourceHashes = sourceHashes
   s.diskDigests = diskDigests
   s.rootFiles = projectRootFilesFromConfigs(configs, false)
@@ -439,6 +631,7 @@ func missingRootInputs(configs []*shimtsoptions.ParsedCommandLine, sourceHashes
 func (s *graphSession) buildDump() (graph.Dump, error) {
   program := s.compiler.Program()
   built := graph.Build(program)
+  graph.ApplyArtifacts(built, s.artifacts)
   // One texts map feeds both the spans and the manifest digests, so the bytes a
   // span points into are provably the bytes the manifest attests to.
   texts := graph.SourceTexts(program)
@@ -449,14 +642,7 @@ func (s *graphSession) buildDump() (graph.Dump, error) {
     graph.GitIgnoredFiles(s.cwd, built),
     texts,
     graph.DumpOrigin{
-      Provenance: graph.NewProvenance(
-        serveProducer(),
-        fullSnapshotCapabilities,
-        s.configDigests,
-        s.roots,
-        texts,
-        s.diskDigests,
-      ),
+      Provenance:  s.provenance(texts),
       Diagnostics: graph.NewDiagnostics(program),
     },
   )
@@ -661,8 +847,19 @@ func changedSources(previous map[string][sha256.Size]byte) (map[string]string, b
 }
 
 type diskState struct {
-  Hash   [sha256.Size]byte
-  Exists bool
+  Hash         [sha256.Size]byte
+  Exists       bool
+  Realpath     string
+  IdentityOnly bool
+}
+
+// auxiliaryInput distinguishes speculative inputs whose contents select the
+// build universe from the lexical spelling of the source the compiler already
+// selected. The resident source hash owns the latter's contents; this input
+// owns only whether the spelling still reaches the same physical file.
+type auxiliaryInput struct {
+  path         string
+  identityOnly bool
 }
 
 // captureDiskStates records the freshness state of speculative resolution
@@ -671,29 +868,35 @@ type diskState struct {
 // Windows), so any path that is neither a readable file nor a directory is
 // recorded as absent instead of failing the snapshot: the recorded state only
 // needs to flip when the candidate becomes resolvable.
-func captureDiskStates(paths []string) map[string]diskState {
-  states := make(map[string]diskState, len(paths))
-  for _, path := range paths {
-    content, err := os.ReadFile(path)
+func captureDiskStates(inputs []auxiliaryInput) map[string]diskState {
+  states := make(map[string]diskState, len(inputs))
+  for _, input := range inputs {
+    state := diskState{IdentityOnly: input.identityOnly}
+    content, err := os.ReadFile(input.path)
     if err != nil {
-      if info, statErr := os.Stat(path); statErr == nil && info.IsDir() {
-        states[path] = diskState{Exists: true}
-      } else {
-        states[path] = diskState{}
+      if info, statErr := os.Stat(input.path); statErr == nil && info.IsDir() {
+        state.Exists = true
+        state.Realpath = diskRealpath(input.path)
       }
+      states[input.path] = state
       continue
     }
-    states[path] = diskState{Hash: sha256.Sum256(content), Exists: true}
+    state.Exists = true
+    state.Realpath = diskRealpath(input.path)
+    if !input.identityOnly {
+      state.Hash = sha256.Sum256(content)
+    }
+    states[input.path] = state
   }
   return states
 }
 
 func diskStatesChanged(previous map[string]diskState) bool {
-  paths := make([]string, 0, len(previous))
-  for path := range previous {
-    paths = append(paths, path)
+  inputs := make([]auxiliaryInput, 0, len(previous))
+  for path, state := range previous {
+    inputs = append(inputs, auxiliaryInput{path: path, identityOnly: state.IdentityOnly})
   }
-  current := captureDiskStates(paths)
+  current := captureDiskStates(inputs)
   for path, state := range previous {
     if current[path] != state {
       return true
@@ -702,16 +905,16 @@ func diskStatesChanged(previous map[string]diskState) bool {
   return false
 }
 
-func auxiliaryInputs(program *driver.Program, configs []*shimtsoptions.ParsedCommandLine, cwd string) []string {
-  inputs := []string{
-    filepath.Join(cwd, ".gitignore"),
-    filepath.Join(cwd, ".git", "info", "exclude"),
-    filepath.Join(cwd, "package.json"),
-    filepath.Join(cwd, "package-lock.json"),
-    filepath.Join(cwd, "pnpm-lock.yaml"),
-    filepath.Join(cwd, "yarn.lock"),
-    filepath.Join(cwd, "bun.lock"),
-    filepath.Join(cwd, "bun.lockb"),
+func auxiliaryInputs(program *driver.Program, configs []*shimtsoptions.ParsedCommandLine, cwd string) []auxiliaryInput {
+  inputs := []auxiliaryInput{
+    {path: filepath.Join(cwd, ".gitignore")},
+    {path: filepath.Join(cwd, ".git", "info", "exclude")},
+    {path: filepath.Join(cwd, "package.json")},
+    {path: filepath.Join(cwd, "package-lock.json")},
+    {path: filepath.Join(cwd, "pnpm-lock.yaml")},
+    {path: filepath.Join(cwd, "yarn.lock")},
+    {path: filepath.Join(cwd, "bun.lock")},
+    {path: filepath.Join(cwd, "bun.lockb")},
   }
   for _, source := range program.TSProgram.SourceFiles() {
     file := source.FileName()
@@ -719,12 +922,18 @@ func auxiliaryInputs(program *driver.Program, configs []*shimtsoptions.ParsedCom
       continue
     }
     directory := filepath.Dir(file)
-    inputs = appendAncestorInputs(inputs, directory, cwd)
+    for _, path := range appendAncestorInputs(nil, directory, cwd) {
+      inputs = append(inputs, auxiliaryInput{path: path})
+    }
     for _, reference := range source.ReferencedFiles {
-      inputs = append(inputs, driver.FileCandidates(filepath.Join(directory, filepath.FromSlash(reference.FileName)))...)
+      for _, path := range driver.FileCandidates(filepath.Join(directory, filepath.FromSlash(reference.FileName))) {
+        inputs = append(inputs, auxiliaryInput{path: path})
+      }
     }
     for _, reference := range source.TypeReferenceDirectives {
-      inputs = append(inputs, driver.TypeReferenceCandidates(configs, directory, cwd, reference.FileName)...)
+      for _, path := range driver.TypeReferenceCandidates(configs, directory, cwd, reference.FileName) {
+        inputs = append(inputs, auxiliaryInput{path: path})
+      }
     }
     for _, specifier := range driver.SourceModuleSpecifiers(source) {
       context := driver.ModuleResolutionContext{
@@ -738,7 +947,7 @@ func auxiliaryInputs(program *driver.Program, configs []*shimtsoptions.ParsedCom
       }
       resolved := program.TSProgram.GetResolvedModuleFromModuleSpecifier(source, specifier)
       if resolved != nil && resolved.IsResolved() {
-        inputs = append(inputs, driver.ModuleResolutionPredecessors(
+        predecessors := driver.ModuleResolutionPredecessors(
           configs,
           directory,
           cwd,
@@ -746,10 +955,18 @@ func auxiliaryInputs(program *driver.Program, configs []*shimtsoptions.ParsedCom
           resolved.ResolvedFileName,
           program.FS.UseCaseSensitiveFileNames(),
           context,
-        )...)
+        )
+        for _, path := range predecessors {
+          inputs = append(inputs, auxiliaryInput{
+            path:         path,
+            identityOnly: sameExistingAuxiliaryPath(path, resolved.ResolvedFileName),
+          })
+        }
         continue
       }
-      inputs = append(inputs, driver.ModuleResolutionCandidates(configs, directory, cwd, specifier.Text(), context)...)
+      for _, path := range driver.ModuleResolutionCandidates(configs, directory, cwd, specifier.Text(), context) {
+        inputs = append(inputs, auxiliaryInput{path: path})
+      }
     }
   }
   // Config `types` entries request type packages without any source syntax, so
@@ -760,10 +977,46 @@ func auxiliaryInputs(program *driver.Program, configs []*shimtsoptions.ParsedCom
       continue
     }
     for _, name := range parsed.ParsedConfig.CompilerOptions.Types {
-      inputs = append(inputs, driver.TypeReferenceCandidates(configs, parsed.GetCurrentDirectory(), cwd, name)...)
+      for _, path := range driver.TypeReferenceCandidates(configs, parsed.GetCurrentDirectory(), cwd, name) {
+        inputs = append(inputs, auxiliaryInput{path: path})
+      }
     }
   }
-  return compactSortedStrings(inputs)
+  return compactAuxiliaryInputs(inputs)
+}
+
+func sameExistingAuxiliaryPath(left, right string) bool {
+  leftInfo, err := os.Stat(left)
+  if err != nil {
+    return false
+  }
+  rightInfo, err := os.Stat(right)
+  return err == nil && os.SameFile(leftInfo, rightInfo)
+}
+
+func compactAuxiliaryInputs(inputs []auxiliaryInput) []auxiliaryInput {
+  byPath := make(map[string]auxiliaryInput, len(inputs))
+  for _, input := range inputs {
+    if strings.TrimSpace(input.path) == "" {
+      continue
+    }
+    if previous, exists := byPath[input.path]; exists {
+      // A path that also participates as a manifest or other content-bearing
+      // input keeps the stronger content-sensitive contract.
+      input.identityOnly = previous.identityOnly && input.identityOnly
+    }
+    byPath[input.path] = input
+  }
+  paths := make([]string, 0, len(byPath))
+  for path := range byPath {
+    paths = append(paths, path)
+  }
+  sort.Strings(paths)
+  output := make([]auxiliaryInput, 0, len(paths))
+  for _, path := range paths {
+    output = append(output, byPath[path])
+  }
+  return output
 }
 
 func appendAncestorInputs(inputs []string, directory, stop string) []string {
@@ -792,9 +1045,23 @@ func runServe(args []string) int {
   fs.SetOutput(stderr)
   cwdFlag := fs.String("cwd", "", "project root (defaults to process cwd)")
   tsconfigFlag := fs.String("tsconfig", "tsconfig.json", "project tsconfig path")
+  artifactsFlag := fs.String(
+    "artifacts",
+    "",
+    "path to the artifacts a plugin published (JSON); absent or missing means none",
+  )
   if err := fs.Parse(args); err != nil {
     return 2
   }
+  artifacts, artifactsErr := graph.LoadArtifacts(strings.TrimSpace(*artifactsFlag))
+  if artifactsErr != nil {
+    fmt.Fprintf(
+      stderr,
+      "ttscgraph: could not read the published artifacts: %v\n",
+      artifactsErr,
+    )
+    return 1
+  }
 
   cwd := strings.TrimSpace(*cwdFlag)
   if cwd == "" {
@@ -811,10 +1078,22 @@ func runServe(args []string) int {
   cwd = shimtspath.ResolvePath(cwd)
   tsconfig := strings.TrimSpace(*tsconfigFlag)
 
-  return serveSnapshots(os.Stdin, stdout, cwd, tsconfig)
+  return serveSnapshotsWithArtifacts(os.Stdin, stdout, cwd, tsconfig, artifacts)
 }
 
 func serveSnapshots(input io.Reader, output io.Writer, cwd, tsconfig string) int {
+  return serveSnapshotsWithArtifacts(input, output, cwd, tsconfig, nil)
+}
+
+// serveSnapshotsWithArtifacts is the loop the serve command runs, and
+// serveSnapshots is it with nothing published — the shape every existing case
+// drives, unchanged.
+func serveSnapshotsWithArtifacts(
+  input io.Reader,
+  output io.Writer,
+  cwd, tsconfig string,
+  artifacts []graph.Artifact,
+) int {
   scanner := bufio.NewScanner(input)
   scanner.Buffer(make([]byte, 64*1024), 1024*1024)
   encoder := json.NewEncoder(output)
@@ -863,7 +1142,7 @@ func serveSnapshots(input io.Reader, output io.Writer, cwd, tsconfig string) int
     var loadDuration time.Duration
     if session == nil {
       loadStarted := time.Now()
-      created, err := newGraphSession(cwd, tsconfig)
+      created, err := newGraphSessionWithArtifacts(cwd, tsconfig, artifacts)
       loadDuration = time.Since(loadStarted)
       if err != nil {
         if err := encodeServeResponseWithTrace(
@@ -893,6 +1172,18 @@ func serveSnapshots(input io.Reader, output io.Writer, cwd, tsconfig string) int
     }
     session.requestProtocol = request.GraphSnapshotVersion
     session.requestProtocolSelected = true
+    if replaced, err := session.adoptArtifacts(request.Artifacts); err != nil {
+      if err := encodeServeResponseWithTrace(encoder, errorResponse(
+        request.ID,
+        fmt.Sprintf("ttscgraph: could not read the published artifacts: %v", err),
+      ), requestStarted, loadDuration, 0, 0); err != nil {
+        fmt.Fprintf(stderr, "ttscgraph: write serve response: %v\n", err)
+        return 1
+      }
+      continue
+    } else if replaced {
+      session.invalidateArtifacts()
+    }
     var dump *graph.Dump
     var snapshot *serveGraphSnapshot
     var mode string
@@ -906,6 +1197,12 @@ func serveSnapshots(input io.Reader, output io.Writer, cwd, tsconfig string) int
       dump, mode, changed, err = session.Snapshot()
     }
     response := newServeResponse(request.ID)
+    // The envelope answers for THIS session, not for the command in general. An
+    // `unchanged` response carries no dump, so the envelope is the only place a
+    // client learns what this server proves — and a session holding artifacts
+    // publishes a dump that claims them. Leaving the shared list here made the
+    // envelope and the dump disagree on the one frame that has no dump to check.
+    response.Capabilities = session.capabilities()
     response.Dump = dump
     response.Snapshot = snapshot
     response.Mode = mode