ttsc 0.27.0 → 0.28.0

package/cmd/graphbench/main.go

@@ -29,10 +29,16 @@ type metrics struct {
   Nodes         int            `json:"nodes"`
   ExternalNodes int            `json:"externalNodes"`
   Edges         map[string]int `json:"edges"`
-  TotalEdges    int            `json:"totalEdges"`
-  SymbolFiles   int            `json:"symbolFiles"`
-  CoveredFiles  int            `json:"coveredFiles"`
-  Coverage      float64        `json:"coverage"`
+  // EdgeVocabulary names which of the three edge-kind vocabularies Edges is
+  // keyed by, so a reader comparing these numbers against a dump does not
+  // compare the wrong things. Build produces *internal* kinds; a dump carries
+  // finer *wire* kinds (value-call splits into calls/instantiates/renders);
+  // the viewer folds wire kinds onto *display* families.
+  EdgeVocabulary string  `json:"edgeVocabulary"`
+  TotalEdges     int     `json:"totalEdges"`
+  SymbolFiles    int     `json:"symbolFiles"`
+  CoveredFiles   int     `json:"coveredFiles"`
+  Coverage       float64 `json:"coverage"`
 }
 
 func main() {
@@ -82,10 +88,13 @@ func run() int {
 // counts, edges per kind, and fair coverage (workspace files holding at least one
 // node that an edge connects to a node in another file).
 func summarize(g *graph.Graph, sourceFiles int) metrics {
-  edges := map[string]int{
-    string(graph.EdgeHeritage):  0,
-    string(graph.EdgeValueCall): 0,
-    string(graph.EdgeTypeRef):   0,
+  // Seeded with every kind Build can produce, so a family that happened not to
+  // occur reports 0 rather than vanishing from the object. Three of the seven
+  // used to be seeded and the map grew the rest on first sight, which meant the
+  // reported shape depended on the project measured.
+  edges := map[string]int{}
+  for _, kind := range graph.EdgeKinds() {
+    edges[string(kind)] = 0
   }
   for _, edge := range g.Edges {
     edges[string(edge.Kind)]++
@@ -123,13 +132,14 @@ func summarize(g *graph.Graph, sourceFiles int) metrics {
   }
 
   return metrics{
-    SourceFiles:   sourceFiles,
-    Nodes:         len(g.Nodes),
-    ExternalNodes: external,
-    Edges:         edges,
-    TotalEdges:    len(g.Edges),
-    SymbolFiles:   len(symbolFiles),
-    CoveredFiles:  len(coveredFiles),
-    Coverage:      coverage,
+    SourceFiles:    sourceFiles,
+    Nodes:          len(g.Nodes),
+    ExternalNodes:  external,
+    Edges:          edges,
+    EdgeVocabulary: "internal",
+    TotalEdges:     len(g.Edges),
+    SymbolFiles:    len(symbolFiles),
+    CoveredFiles:   len(coveredFiles),
+    Coverage:       coverage,
   }
 }

package/cmd/graphdump/main.go

@@ -6,8 +6,10 @@
 package main
 
 import (
+  "errors"
   "flag"
   "fmt"
+  "io"
   "os"
   "path/filepath"
 
@@ -17,18 +19,37 @@ import (
   "github.com/samchon/ttsc/packages/ttsc/internal/graph"
 )
 
+// Package-level streams so command tests can capture I/O without patching the
+// os globals, and argv arrives as a parameter for the same reason. Both mirror
+// the shipped sibling in cmd/ttscgraph, whose capability claim is tested the
+// same way; this command's claim went undefended because it had neither seam.
+var (
+  stdout io.Writer = os.Stdout
+  stderr io.Writer = os.Stderr
+)
+
 func main() {
-  os.Exit(run())
+  os.Exit(run(os.Args[1:]))
 }
 
-func run() int {
-  cwd := flag.String("cwd", ".", "project root")
-  tsconfig := flag.String("tsconfig", "tsconfig.json", "tsconfig path, relative to cwd")
-  pretty := flag.Bool("pretty", false, "indent the JSON output")
-  flag.Parse()
+func run(args []string) int {
+  fs := flag.NewFlagSet("graphdump", flag.ContinueOnError)
+  fs.SetOutput(stderr)
+  cwd := fs.String("cwd", ".", "project root")
+  tsconfig := fs.String("tsconfig", "tsconfig.json", "tsconfig path, relative to cwd")
+  pretty := fs.Bool("pretty", false, "indent the JSON output")
+  if err := fs.Parse(args); err != nil {
+    // `-h` asks for the usage this just printed, so it is a request that
+    // succeeded rather than an argument that failed. Under the global flag set
+    // this command used to read, `ExitOnError` already exited 0 for it.
+    if errors.Is(err, flag.ErrHelp) {
+      return 0
+    }
+    return 2
+  }
 
   // Resolve the project root the same way LoadProgram does (absolute, then
-  // tsgo-normalized) so the schema-v6 mapper receives the same canonical root
+  // tsgo-normalized) so the dump path mapper receives the same canonical root
   // grammar and drive-letter case as the compiler's source paths.
   root := *cwd
   if abs, err := filepath.Abs(root); err == nil {
@@ -38,11 +59,11 @@ func run() int {
 
   prog, _, err := driver.LoadProgram(root, *tsconfig, driver.LoadProgramOptions{})
   if err != nil {
-    fmt.Fprintf(os.Stderr, "graphdump: could not load %s/%s: %v\n", root, *tsconfig, err)
+    fmt.Fprintf(stderr, "graphdump: could not load %s/%s: %v\n", root, *tsconfig, err)
     return 1
   }
   if prog == nil {
-    fmt.Fprintf(os.Stderr, "graphdump: could not load %s/%s\n", root, *tsconfig)
+    fmt.Fprintf(stderr, "graphdump: could not load %s/%s\n", root, *tsconfig)
     return 1
   }
   defer func() { _ = prog.Close() }()
@@ -62,7 +83,11 @@ func run() int {
       // No version: this tool is built from the tree on demand and never
       // stamped, and an invented one would be worse than an absent one.
       graph.Producer{Tool: "graphdump", Typescript: graph.TypescriptVersion()},
-      []string{graph.CapabilitySourceDigests},
+      // The declaration walk is the shipped one, so this dump carries every
+      // documentation tag and must say so: under the capability contract an
+      // absent claim means the producer never looked, which would make a
+      // consumer read a tagged declaration as citing nothing.
+      []string{graph.CapabilitySourceDigests, graph.CapabilityDocTags},
       nil,
       nil,
       texts,
@@ -70,9 +95,9 @@ func run() int {
     ),
   }, *pretty)
   if err != nil {
-    fmt.Fprintf(os.Stderr, "graphdump: %v\n", err)
+    fmt.Fprintf(stderr, "graphdump: %v\n", err)
     return 1
   }
-  fmt.Println(string(data))
+  fmt.Fprintln(stdout, string(data))
   return 0
 }

package/cmd/graphdump/run_declares_the_capability_its_output_carries_test.go

@@ -0,0 +1,137 @@
+package main
+
+import (
+  "bytes"
+  "encoding/json"
+  "os"
+  "path/filepath"
+  "slices"
+  "strings"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/graph"
+)
+
+// TestRunDeclaresTheCapabilityItsOutputCarries verifies that every capability
+// this command declares is paired with the output that backs it, and that a
+// project carrying no documentation tag emits that field nowhere.
+//
+// The claim is a separate literal from the shipped `ttscgraph dump`'s, so the
+// test that guards that one guards nothing here: deleting graph.CapabilityDocTags
+// from this command's list used to break nothing at all, in a package that had
+// never had a test file. The claim matters because the two states a consumer must
+// distinguish — "this declaration cites nothing" and "this producer never
+// looked" — are the same absent field, so a dump that carries tags and forgets to
+// say so is read as a repository where nothing cites anything.
+//
+// The declared set is compared whole rather than member by member, so a
+// capability added to the list arrives with the evidence for it or fails here.
+//
+//  1. Run the command over a project with a tag, capturing stdout.
+//  2. Assert the declared set is exactly what this command claims, and that each
+//     claim is backed: a tag in the output, and a digested source.
+//  3. Run it over a project with no tag and assert the field appears nowhere,
+//     while both claims still do.
+func TestRunDeclaresTheCapabilityItsOutputCarries(t *testing.T) {
+  tagged := runGraphdump(t, `/** @evidence docs/a.md#x Cited. */
+export function subject(): void {}
+`)
+  untagged := runGraphdump(t, `/** Ordinary documentation. */
+export function subject(): void {}
+`)
+
+  declared := []string{graph.CapabilityDocTags, graph.CapabilitySourceDigests}
+  slices.Sort(declared)
+  for name, raw := range map[string]string{"tagged": tagged, "untagged": untagged} {
+    var parsed struct {
+      Provenance struct {
+        Capabilities []string `json:"capabilities"`
+        Sources      []struct {
+          File          string `json:"file"`
+          CheckerDigest string `json:"checkerDigest"`
+        } `json:"sources"`
+      } `json:"provenance"`
+    }
+    if err := json.Unmarshal([]byte(raw), &parsed); err != nil {
+      t.Fatalf("%s dump is not JSON: %v", name, err)
+    }
+    got := slices.Clone(parsed.Provenance.Capabilities)
+    slices.Sort(got)
+    if !slices.Equal(got, declared) {
+      t.Fatalf("%s dump declares %v, want %v; an absent claim means the producer "+
+        "never looked, so a tagged declaration reads as citing nothing and a "+
+        "digested source reads as unread",
+        name, got, declared)
+    }
+    // The sourceDigests claim, backed the same way the docTags claim is: a
+    // declared capability whose output carries nothing is the tautology this
+    // test exists to avoid.
+    digested := 0
+    for _, source := range parsed.Provenance.Sources {
+      if source.CheckerDigest != "" {
+        digested++
+      }
+    }
+    if digested == 0 {
+      t.Fatalf("%s dump declares %q over %d sources, none of which carries a checker digest",
+        name, graph.CapabilitySourceDigests, len(parsed.Provenance.Sources))
+    }
+  }
+
+  if !strings.Contains(tagged, `"docs/a.md#x Cited."`) {
+    t.Fatalf("the tagged dump carried no tag text")
+  }
+  // Read the raw document rather than a decoded slice: an absent field and an
+  // empty one decode identically, and absent is what the wire contract says. The
+  // key is matched with its colon, because the capability shares the name and
+  // rides the same document as a bare string.
+  if strings.Contains(untagged, `"docTags":`) {
+    t.Fatalf("the untagged dump carried a docTags field; it must be absent")
+  }
+  if !strings.Contains(tagged, `"docTags":`) {
+    t.Fatalf("the tagged dump carried no docTags field, so the check above proves nothing")
+  }
+}
+
+// runGraphdump runs the command over a one-file project and returns its stdout.
+//
+// It goes through run(args) and the package streams rather than through os.Args,
+// flag.CommandLine, and an os.Stdout pipe. Those seams exist on the shipped
+// sibling for this reason, and this command grew them so its own claim could be
+// asserted against its own output without patching process globals.
+func runGraphdump(t *testing.T, source string) string {
+  t.Helper()
+  root := t.TempDir()
+  writeGraphdumpFile(t, filepath.Join(root, "tsconfig.json"), `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "strict": true,
+    "rootDir": "src",
+    "outDir": "dist"
+  },
+  "files": ["src/main.ts"]
+}
+`)
+  writeGraphdumpFile(t, filepath.Join(root, "src", "main.ts"), source)
+
+  var out, errOut bytes.Buffer
+  restoreStdout, restoreStderr := stdout, stderr
+  stdout, stderr = &out, &errOut
+  defer func() { stdout, stderr = restoreStdout, restoreStderr }()
+
+  if code := run([]string{"--cwd", root, "--tsconfig", "tsconfig.json"}); code != 0 {
+    t.Fatalf("graphdump exited %d: %s", code, errOut.String())
+  }
+  return out.String()
+}
+
+func writeGraphdumpFile(t *testing.T, path, content string) {
+  t.Helper()
+  if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+    t.Fatal(err)
+  }
+  if err := os.WriteFile(path, []byte(content), 0o644); err != nil {
+    t.Fatal(err)
+  }
+}

package/cmd/graphdump/run_reports_an_unknown_flag_without_exiting_the_process_test.go

@@ -0,0 +1,56 @@
+package main
+
+import (
+  "bytes"
+  "strings"
+  "testing"
+)
+
+// TestRunReportsAnUnknownFlagWithoutExitingTheProcess verifies that a bad
+// argument returns an exit code and writes usage to the command's own stream,
+// instead of terminating the process.
+//
+// This is the negative twin of the capability case and the reason the seams
+// exist. The command used to parse flag.CommandLine, whose default error
+// handling is flag.ExitOnError: a malformed argument called os.Exit(2) from
+// inside run, which no test can observe and which would take a test binary down
+// with it. Nothing else about the command is reachable while that is true.
+//
+//  1. Run the command with an unknown flag, capturing both streams.
+//  2. Assert it returns 2 rather than exiting, and that nothing reached stdout.
+//  3. Assert the usage text went to the command's stderr stream.
+//  4. Assert `-h` still succeeds, because asking for usage is not an error.
+func TestRunReportsAnUnknownFlagWithoutExitingTheProcess(t *testing.T) {
+  var out, errOut bytes.Buffer
+  restoreStdout, restoreStderr := stdout, stderr
+  stdout, stderr = &out, &errOut
+  defer func() { stdout, stderr = restoreStdout, restoreStderr }()
+
+  code := run([]string{"--not-a-flag"})
+
+  if code != 2 {
+    t.Fatalf("graphdump exited %d for an unknown flag, want 2", code)
+  }
+  if out.Len() != 0 {
+    t.Fatalf("a rejected invocation wrote %q to stdout; the viewer pipeline parses that stream as JSON", out.String())
+  }
+  if !strings.Contains(errOut.String(), "not-a-flag") {
+    t.Fatalf("stderr does not name the rejected flag: %q", errOut.String())
+  }
+  if !strings.Contains(errOut.String(), "-tsconfig") {
+    t.Fatalf("stderr carried no usage text: %q", errOut.String())
+  }
+
+  // The negative twin of the rejection: `flag.ContinueOnError` reports `-h` as
+  // an error too, and mapping every parse failure to 2 would turn the help flag
+  // into a failed invocation. The global flag set this command used to read
+  // exited 0 for it.
+  out.Reset()
+  errOut.Reset()
+  if code := run([]string{"-h"}); code != 0 {
+    t.Fatalf("graphdump exited %d for -h, want 0", code)
+  }
+  if !strings.Contains(errOut.String(), "-tsconfig") {
+    t.Fatalf("-h printed no usage text: %q", errOut.String())
+  }
+}

package/cmd/graphdump/run_reports_an_unloadable_project_without_printing_a_dump_test.go

@@ -0,0 +1,46 @@
+package main
+
+import (
+  "bytes"
+  "strings"
+  "testing"
+)
+
+// TestRunReportsAnUnloadableProjectWithoutPrintingADump verifies that a project
+// the command cannot load exits non-zero, prints nothing to stdout, and names
+// what it could not load.
+//
+// The benchmark viewer pipeline runs this command through `execFileSync`, which
+// raises only on a non-zero exit and otherwise parses stdout as JSON. Every
+// failure path here therefore has to be a non-zero exit: turning one into 0
+// hands the pipeline an empty string, and the caller dies inside its JSON parse
+// with an opaque error instead of reading the diagnostic this command already
+// wrote. All three failure paths used to be unpinned, so replacing every
+// `return 1` with `return 0` broke no test.
+//
+//  1. Run the command against a tsconfig that does not exist.
+//  2. Assert it returns 1 and wrote nothing to stdout.
+//  3. Assert stderr names the command and the path it could not load.
+func TestRunReportsAnUnloadableProjectWithoutPrintingADump(t *testing.T) {
+  root := t.TempDir()
+
+  var out, errOut bytes.Buffer
+  restoreStdout, restoreStderr := stdout, stderr
+  stdout, stderr = &out, &errOut
+  defer func() { stdout, stderr = restoreStdout, restoreStderr }()
+
+  code := run([]string{"--cwd", root, "--tsconfig", "absent.json"})
+
+  if code != 1 {
+    t.Fatalf("graphdump exited %d for an unloadable project, want 1", code)
+  }
+  if out.Len() != 0 {
+    t.Fatalf("a failed run wrote %q to stdout; the viewer pipeline parses that stream as JSON", out.String())
+  }
+  if !strings.Contains(errOut.String(), "graphdump:") {
+    t.Fatalf("stderr does not identify the command: %q", errOut.String())
+  }
+  if !strings.Contains(errOut.String(), "absent.json") {
+    t.Fatalf("stderr does not name the tsconfig it could not load: %q", errOut.String())
+  }
+}

package/cmd/ttsc/api_transform.go

@@ -26,6 +26,13 @@ type apiTransformResult struct {
   // content can influence a transformed module, so bundler caches invalidate
   // soundly without per-plugin reporting.
   Graph *driver.TransformGraph `json:"graph,omitempty"`
+  // Dependencies and DependenciesComplete are the envelope's dependency side
+  // channel. This lane runs no plugin transform at all — each output is the
+  // file's own parsed text — so every file is complete with an empty list
+  // unless a linked plugin is active and declares otherwise; see
+  // driver.Program.TransformDependenciesFor.
+  Dependencies         map[string][]string `json:"dependencies,omitempty"`
+  DependenciesComplete []string            `json:"dependenciesComplete,omitempty"`
   // HostInputs are absolute native plugin config files evaluated while this
   // generation loaded. JavaScript hosts merge them with descriptor inputs.
   HostInputs         []string           `json:"hostInputs,omitempty"`
@@ -74,6 +81,7 @@ func runAPITransform(args []string) int {
     return 2
   }
   typescript := map[string]string{}
+  var dependencies driver.TransformDependencies
   var graph *driver.TransformGraph
   var hostInputs []string
   var hostInputHashes map[string]*string
@@ -89,18 +97,21 @@ func runAPITransform(args []string) int {
       typescript[apiOutputKey(cwd, file.FileName())] = file.Text()
     }
     diags = append(diags, prog.Diagnostics()...)
+    dependencies = prog.TransformDependenciesFor(cwd)
     hostInputs = prog.PluginHostInputs()
     hostInputHashes = prog.PluginHostInputHashes()
     hostInputRealpaths = prog.PluginHostInputRealpaths()
   }
 
   result := apiTransformResult{
-    Diagnostics:        make([]apiCompileDiagnostic, 0, len(diags)),
-    Graph:              graph,
-    HostInputs:         hostInputs,
-    HostInputHashes:    hostInputHashes,
-    HostInputRealpaths: hostInputRealpaths,
-    TypeScript:         typescript,
+    Dependencies:         dependencies.Dependencies,
+    DependenciesComplete: dependencies.Complete,
+    Diagnostics:          make([]apiCompileDiagnostic, 0, len(diags)),
+    Graph:                graph,
+    HostInputs:           hostInputs,
+    HostInputHashes:      hostInputHashes,
+    HostInputRealpaths:   hostInputRealpaths,
+    TypeScript:           typescript,
   }
   for _, diag := range diags {
     result.Diagnostics = append(result.Diagnostics, toAPICompileDiagnostic(diag))

package/cmd/ttscgraph/dump.go

@@ -23,6 +23,11 @@ func runDump(args []string) int {
   cwdFlag := fs.String("cwd", "", "project root (defaults to process cwd)")
   tsconfigFlag := fs.String("tsconfig", "tsconfig.json", "project tsconfig path")
   prettyFlag := fs.Bool("pretty", false, "indent the JSON output")
+  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
   }
@@ -37,7 +42,7 @@ func runDump(args []string) int {
     cwd = resolved
   }
   // Resolve the project root the same way LoadProgram does (absolute, then
-  // tsgo-normalized) so the schema-v6 mapper receives the same canonical root
+  // tsgo-normalized) so the dump path mapper receives the same canonical root
   // grammar and drive-letter case as the compiler's source paths.
   if abs, err := filepath.Abs(cwd); err == nil {
     cwd = abs
@@ -57,9 +62,19 @@ func runDump(args []string) int {
   defer func() { _ = prog.Close() }()
 
   g := graph.Build(prog)
+  // The artifacts arrive from a plugin that parsed documents this Program never
+  // read, so they are a second producer's facts and the origin says so. Applying
+  // them before the dump is what turns a citation of a document section from a
+  // token into a relation.
+  artifacts, err := graph.LoadArtifacts(strings.TrimSpace(*artifactsFlag))
+  if err != nil {
+    fmt.Fprintf(stderr, "ttscgraph: could not read the published artifacts: %v\n", err)
+    return 1
+  }
+  graph.ApplyArtifacts(g, artifacts)
   ignored := graph.GitIgnoredFiles(cwd, g)
   texts := graph.SourceTexts(prog)
-  origin, err := dumpOrigin(prog, texts)
+  origin, err := dumpOrigin(prog, texts, strings.TrimSpace(*artifactsFlag) != "")
   if err != nil {
     fmt.Fprintf(stderr, "ttscgraph: %v\n", err)
     return 1
@@ -89,7 +104,16 @@ func runDump(args []string) int {
 // saw the project, so it carries the same provenance a served snapshot does:
 // without it the file is a pile of facts with no way to tell which program, or
 // which day, they describe.
-func dumpOrigin(prog *driver.Program, texts map[string]string) (graph.DumpOrigin, error) {
+// dumpOrigin builds the provenance for one dump. askedForArtifacts is what
+// turns the artifact capability from a guess into a claim: a producer that was
+// never pointed at a publisher did not look, and saying it did would make a
+// project with no artifacts indistinguishable from one whose artifacts were
+// never requested.
+func dumpOrigin(
+  prog *driver.Program,
+  texts map[string]string,
+  askedForArtifacts bool,
+) (graph.DumpOrigin, error) {
   configs, err := parsedConfigs(prog)
   if err != nil {
     return graph.DumpOrigin{}, err
@@ -102,15 +126,23 @@ func dumpOrigin(prog *driver.Program, texts map[string]string) (graph.DumpOrigin
   if err != nil {
     return graph.DumpOrigin{}, err
   }
+  capabilities := fullSnapshotCapabilities
+  if askedForArtifacts {
+    capabilities = append(append([]string{}, capabilities...), graph.CapabilityArtifactNodes)
+  }
+  provenance := graph.NewProvenance(
+    serveProducer(),
+    capabilities,
+    fileDigests(configHashes),
+    rootFileEntries(projectRootFilesFromConfigs(configs, false)),
+    texts,
+    diskDigests,
+  )
+  if askedForArtifacts {
+    provenance.ArtifactProducer = &graph.Producer{Tool: "@ttsc/lint graph-nodes"}
+  }
   return graph.DumpOrigin{
-    Provenance: graph.NewProvenance(
-      serveProducer(),
-      fullSnapshotCapabilities,
-      fileDigests(configHashes),
-      rootFileEntries(projectRootFilesFromConfigs(configs, false)),
-      texts,
-      diskDigests,
-    ),
+    Provenance:  provenance,
     Diagnostics: graph.NewDiagnostics(prog),
   }, nil
 }

package/cmd/ttscgraph/run_dump_claims_artifacts_only_when_it_asked_test.go

@@ -0,0 +1,135 @@
+package main
+
+import (
+  "bytes"
+  "encoding/json"
+  "os"
+  "path/filepath"
+  "slices"
+  "strings"
+  "testing"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/graph"
+)
+
+// TestRunDumpClaimsArtifactsOnlyWhenItAsked verifies that the artifact
+// capability is a statement about what this producer did, not about what it
+// found.
+//
+// The two states a consumer must distinguish are "this project publishes no
+// artifacts" and "this producer was never pointed at a publisher". Both are the
+// same absent nodes, so only the claim separates them — and a producer that
+// claimed unconditionally would make a project with no lint install look like a
+// project whose documents cite nothing. The second producer is named for the
+// same reason: these facts did not come from this Program, and the dump's
+// one-generation contract stays honest by saying so rather than by hiding it.
+//
+//  1. Dump a project with no `--artifacts`, and assert neither the claim nor the
+//     second producer appears, and that the citation stays a token.
+//  2. Dump the same project with a published set, and assert both appear and the
+//     citation resolved to a node carrying its heading and its line.
+func TestRunDumpClaimsArtifactsOnlyWhenItAsked(t *testing.T) {
+  root := t.TempDir()
+  writeGraphFile(t, filepath.Join(root, "tsconfig.json"), `{
+  "compilerOptions": { "target": "ES2022", "module": "commonjs", "strict": true },
+  "files": ["src/main.ts"]
+}
+`)
+  writeGraphFile(t, filepath.Join(root, "src", "main.ts"), `/** @evidence docs/sale.md#pricing States the rule. */
+export function priced(): void {}
+`)
+
+  plain := decodeArtifactDump(t, runDumpForArtifacts(t, root, ""))
+  if slices.Contains(plain.Provenance.Capabilities, graph.CapabilityArtifactNodes) {
+    t.Fatalf("a dump that was never pointed at a publisher claimed %q", graph.CapabilityArtifactNodes)
+  }
+  if plain.Provenance.ArtifactProducer != nil {
+    t.Fatal("a dump with no artifacts named a second producer")
+  }
+  for _, node := range plain.Nodes {
+    if node.ID == "docs/sale.md#pricing" {
+      t.Fatal("an unrequested dump fabricated an artifact node")
+    }
+  }
+
+  published := filepath.Join(root, "artifacts.json")
+  if err := os.WriteFile(published, []byte(`[
+  {"address":"docs/sale.md","kind":"markdown_document","readable":"Sale","file":"docs/sale.md","line":1},
+  {"address":"docs/sale.md#pricing","kind":"markdown_section","readable":"Pricing","parent":"docs/sale.md","file":"docs/sale.md","line":7}
+]`), 0o644); err != nil {
+    t.Fatal(err)
+  }
+
+  indexed := decodeArtifactDump(t, runDumpForArtifacts(t, root, published))
+  if !slices.Contains(indexed.Provenance.Capabilities, graph.CapabilityArtifactNodes) {
+    t.Fatalf("a dump that asked declares %v, missing %q",
+      indexed.Provenance.Capabilities, graph.CapabilityArtifactNodes)
+  }
+  if indexed.Provenance.ArtifactProducer == nil {
+    t.Fatal("the artifact nodes came from another Program and the dump did not say so")
+  }
+
+  var section *graph.DumpNode
+  for index := range indexed.Nodes {
+    if indexed.Nodes[index].ID == "docs/sale.md#pricing" {
+      section = &indexed.Nodes[index]
+    }
+  }
+  if section == nil {
+    t.Fatal("the cited section is not a node")
+  }
+  if section.Name != "Pricing" {
+    t.Fatalf("the section is named %q, not the heading text an index exists to hold", section.Name)
+  }
+  if section.Parent != "docs/sale.md" {
+    t.Fatalf("the section's parent is %q, want its document", section.Parent)
+  }
+  if section.Evidence == nil || section.Evidence.StartLine != 7 {
+    t.Fatalf("the section carries no span at its heading: %+v", section.Evidence)
+  }
+  cited := false
+  for _, edge := range indexed.Edges {
+    if edge.Kind == "doc_ref" && edge.To == "docs/sale.md#pricing" {
+      cited = true
+    }
+  }
+  if !cited {
+    t.Fatal("the citation stayed a token; it has to resolve to the node now that one exists")
+  }
+}
+
+// runDumpForArtifacts runs the dump subcommand and returns its stdout.
+func runDumpForArtifacts(t *testing.T, root, artifacts string) string {
+  t.Helper()
+  args := []string{"dump", "--cwd", root, "--tsconfig", "tsconfig.json"}
+  if artifacts != "" {
+    args = append(args, "--artifacts", artifacts)
+  }
+  var out, errOut bytes.Buffer
+  restoreStdout, restoreStderr := stdout, stderr
+  stdout, stderr = &out, &errOut
+  defer func() { stdout, stderr = restoreStdout, restoreStderr }()
+
+  if code := run(args); code != 0 {
+    t.Fatalf("dump exited %d: %s", code, errOut.String())
+  }
+  return out.String()
+}
+
+type artifactDump struct {
+  Provenance struct {
+    Capabilities     []string        `json:"capabilities"`
+    ArtifactProducer *graph.Producer `json:"artifactProducer"`
+  } `json:"provenance"`
+  Nodes []graph.DumpNode `json:"nodes"`
+  Edges []graph.DumpEdge `json:"edges"`
+}
+
+func decodeArtifactDump(t *testing.T, raw string) artifactDump {
+  t.Helper()
+  var parsed artifactDump
+  if err := json.Unmarshal([]byte(strings.TrimSpace(raw)), &parsed); err != nil {
+    t.Fatalf("dump is not JSON: %v", err)
+  }
+  return parsed
+}