@ttsc/graph 0.27.0 → 0.28.0

package/src/server/runLookup.ts

@@ -1,13 +1,20 @@
-import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { TtscGraphMemory, documentationTarget } from "../model/TtscGraphMemory";
 import { ITtscGraphLookup } from "../structures/ITtscGraphLookup";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { isArtifactNodeKind } from "../structures/TtscGraphArtifactNodeKind";
 import { exportFanIn } from "./exportSurface";
 import { isExternalNode, isSupportPath } from "./pathPolicy";
 import { IRunnerOutput, resultNext } from "./resultNext";
-import { decoratorsOf, signatureOf } from "./runDetails";
+import { decoratorsOf, docTagsOf, signatureOf } from "./runDetails";
 
 // One file should not crowd out the rest of the ranking, so cap hits per file.
 const PER_FILE = 3;
+// The score a citation carrier reports. Citation hits are placed ahead of the
+// ranked list rather than sorted into it, so this value decides no order: it
+// exists because every hit owes a score, and it is high to say what kind of
+// answer this is — an exact match on an address the caller and the author spell
+// identically, not a better guess at a name.
+const CITATION_SCORE = 1000;
 const DEFAULT_LIMIT = 5;
 const MAX_LIMIT = 6;
 
@@ -29,7 +36,12 @@ export function runLookup(
   const wantsInternal = wantsInternalSymbol(queryLc, codeTerms);
   const wantsSupport = wantsSupportSymbol(queryLc);
   const includeExternal = props.includeExternal === true;
-  if (terms.length === 0)
+  // The reverse citation question is answered before the name tokenizer gets a
+  // veto. `subwords` splits on ASCII alphanumerics, so a target written in
+  // another script, or one made only of punctuation, produces no term and used
+  // to return "no searchable terms" while the index held that exact address.
+  const cited = citationHits(graph, props.query, includeExternal);
+  if (terms.length === 0 && cited.length === 0)
     return {
       result: {
         type: "lookup",
@@ -42,7 +54,12 @@ export function runLookup(
     };
 
   const scored: ITtscGraphLookup.IHit[] = [];
-  for (const node of graph.nodes) {
+  // With no term to match, nothing is a name match. The whole-query bonus below
+  // is awarded when every term landed, and no terms trivially satisfies that —
+  // so a query the tokenizer cannot read (an address in another script) would
+  // otherwise return the citation hit followed by arbitrary central symbols,
+  // presented as answers to a name it never matched.
+  for (const node of terms.length === 0 ? [] : graph.nodes) {
     if (node.kind === "file") continue;
     if (!includeExternal && isExternalNode(node)) continue;
     const score = scoreNode(
@@ -69,18 +86,46 @@ export function runLookup(
     scored.push(hit);
   }
 
-  scored.sort((a, b) => b.score - a.score);
+  // A query naming a documentation target is the reverse citation question, and
+  // it is the one an index has to answer: the declarations implementing one
+  // specification are scattered across every file that implements it, so
+  // anything less than an index means searching the repository.
+  //
+  // These are prepended rather than scored in. A tag target is an exact token
+  // the caller typed — `docs/pricing.md#sale`, `POST:/orders` — so a carrier is
+  // not a better fuzzy match than the name hits, it is a different and certain
+  // kind of answer, and name scoring cannot rank the two against each other.
+  const citedIds = new Set(cited.map((hit) => hit.id));
+  const ranked = scored.filter((hit) => !citedIds.has(hit.id));
+  ranked.sort((a, b) => b.score - a.score);
+  ranked.unshift(...cited);
 
   // Diversity: keep at most PER_FILE hits per file while filling up to the limit.
+  //
+  // A citation carrier is exempt. The cap exists so one file's roster cannot
+  // crowd out a name ranking, and a citation is not ranked against anything: it
+  // is an exact match on an address, and a module implementing one specification
+  // across four functions is the ordinary shape of the answer rather than a file
+  // dominating a shortlist. Capping those returned three of five carriers and
+  // called the result complete.
   const limit = bound(props.limit, DEFAULT_LIMIT, 1, MAX_LIMIT);
   const perFile = new Map<string, number>();
   const hits: ITtscGraphLookup.IHit[] = [];
-  for (const hit of scored) {
-    const used = perFile.get(hit.file) ?? 0;
-    if (used >= PER_FILE) continue;
-    perFile.set(hit.file, used + 1);
+  let truncated = false;
+  for (const hit of ranked) {
+    if (hits.length >= limit) {
+      truncated = true;
+      break;
+    }
+    if (!citedIds.has(hit.id)) {
+      const used = perFile.get(hit.file) ?? 0;
+      if (used >= PER_FILE) {
+        truncated = true;
+        continue;
+      }
+      perFile.set(hit.file, used + 1);
+    }
     hits.push(hit);
-    if (hits.length >= limit) break;
   }
 
   // Attach each kept hit's signature only for the shortlist, so the model can
@@ -95,6 +140,7 @@ export function runLookup(
     result: {
       type: "lookup",
       hits,
+      ...(truncated ? { truncated: true } : {}),
     },
     next:
       hits.length === 0
@@ -102,10 +148,16 @@ export function runLookup(
             "outside",
             "No symbol matched, so the graph did not resolve this name.",
           )
-        : resultNext(
-            "answer",
-            "The ranked hits and their signatures resolve the name.",
-          ),
+        : truncated
+          ? resultNext(
+              "answer",
+              "The hits resolve the name, and `truncated` says more matched " +
+                "than the limit returned: raise `limit` for the rest.",
+            )
+          : resultNext(
+              "answer",
+              "The ranked hits and their signatures resolve the name.",
+            ),
   };
 }
 
@@ -293,3 +345,76 @@ function subwords(text: string): string[] {
     .filter((w) => w.length > 0)
     .map((w) => w.toLowerCase());
 }
+
+/**
+ * The declarations whose documentation opens a tag with the address this query
+ * opens with, in file order.
+ *
+ * A caller writing `docs/pricing.md#sale` or `POST:/orders` is asking the
+ * reverse citation question: not what a symbol is, but which code answers to
+ * this specification. Nothing else in the graph can answer it, because the
+ * other end of the relation is a document section rather than a declaration.
+ *
+ * The match is exact, and only a token shaped like an address is one at all —
+ * `documentationTarget` decides that for the query and for every indexed tag,
+ * so the two sides can never disagree about what counts. Fuzzy matching is what
+ * the name scoring above does, and it is wrong here: an address is spelled
+ * identically by the author and the caller, and a near-miss would put a
+ * different specification's implementers in the answer under the same confident
+ * heading.
+ *
+ * Each returned hit carries the tags that matched, so the result says why the
+ * declaration is in it.
+ */
+function citationHits(
+  graph: TtscGraphMemory,
+  query: string,
+  includeExternal: boolean,
+): ITtscGraphLookup.IHit[] {
+  const target = documentationTarget(query);
+  if (target === undefined) return [];
+  const hits: ITtscGraphLookup.IHit[] = [];
+  // The artifact itself leads, when one was published under this address. A
+  // caller asking about `docs/sale.md#pricing` wants what that anchor names —
+  // the heading's own text and where it starts — before it wants the list of
+  // declarations that cite it, and answering only the second half is the gap an
+  // index of tokens had. It is not name-ranked: the address matched exactly.
+  const artifact = graph.node(target);
+  if (artifact !== undefined && isArtifactNodeKind(artifact.kind))
+    hits.push({
+      id: artifact.id,
+      name: artifact.name,
+      kind: artifact.kind,
+      file: artifact.file,
+      line: artifact.evidence?.startLine,
+      score: CITATION_SCORE,
+    });
+  for (const node of graph.citing(target)) {
+    if (node.kind === "file") continue;
+    if (!includeExternal && isExternalNode(node)) continue;
+    // Matched on the node's own tags and elided afterwards. Filtering the
+    // elided text instead dropped the explanation from a hit whose address was
+    // longer than the cap: the node was found by the address and then returned
+    // without the tag that said why.
+    const matched = docTagsOf(
+      node,
+      (tag) => documentationTarget(tag.text) === target,
+    );
+    const hit: ITtscGraphLookup.IHit = {
+      id: node.id,
+      name: node.qualifiedName ?? node.name,
+      kind: node.kind,
+      file: node.file,
+      line: node.evidence?.startLine,
+      // An exact target match is a certain answer rather than a ranked guess.
+      // The score exists so the field is never absent; it does not compete with
+      // the name scores, because these hits are not ordered against them.
+      score: CITATION_SCORE,
+    };
+    const decorators = decoratorsOf(node);
+    if (decorators !== undefined) hit.decorators = decorators;
+    if (matched !== undefined && matched.length > 0) hit.docTags = matched;
+    hits.push(hit);
+  }
+  return hits;
+}

package/src/structures/ITtscGraphApplication.ts

@@ -34,7 +34,9 @@ import { ITtscGraphTrace } from "./ITtscGraphTrace";
  *   the whole answer; do not split it. Name the machinery you expect it to be
  *   made of in its `reinterpretations`, or send none.
  * - `entrypoints`: find where execution starts when entry points are unknown.
- * - `lookup`: locate a named symbol.
+ * - `lookup`: locate a named symbol, or — with a documentation target as the
+ *   query (`docs/pricing.md#sale`, `POST:/orders`) — the declarations whose
+ *   documentation cites it.
  * - `trace`: follow calls or data flow forward or backward from a symbol, or —
  *   with `to` — the path between two symbols when both ends are known, which is
  *   the one call that answers "how does A reach B".

package/src/structures/ITtscGraphDetails.ts

@@ -1,4 +1,5 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
+import { ITtscGraphDocTag } from "./ITtscGraphDocTag";
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
 
 /**
@@ -135,6 +136,18 @@ export namespace ITtscGraphDetails {
     /** Decorators written on this declaration, when any. */
     decorators?: ITtscGraphDecorator[];
 
+    /**
+     * Documentation tags naming what outside the type system this declaration
+     * answers to: a specification section, an API operation, a reference
+     * document (`@evidence docs/pricing.md#sale`, `@reference …`).
+     *
+     * Part of what the declaration is, so it is returned whole like its members
+     * and its values — long text is elided, and nothing else is cut. The tag is
+     * reported as written and never interpreted: the graph does not say the
+     * text resolves to anything or that the claim is true.
+     */
+    docTags?: ITtscGraphDocTag[];
+
     /** Assigned implementation span, when source comes from one. */
     implementation?: ITtscGraphEvidence;
 

package/src/structures/ITtscGraphDocTag.ts

@@ -0,0 +1,45 @@
+/**
+ * One documentation tag TypeScript itself does not recognize, written on a
+ * declaration and carried on its {@link ITtscGraphNode}'s `docTags`.
+ *
+ * A convention attaches a declaration to something outside the type system — a
+ * specification section, an API operation, a reference document — and writes
+ * that attachment as a tag, because the thing on the other end is not a
+ * TypeScript declaration and so cannot be an edge. `@evidence
+ * docs/pricing.md#sale`, `@reference https://…`, and a project's own `@spec`
+ * are one fact in three spellings.
+ *
+ * Reported faithfully, never interpreted. The graph does not say a tag's text
+ * resolves to anything, is covered, or is true — a target naming nothing is
+ * carried exactly as written, the way {@link ITtscGraphDecorator} carries
+ * `@Controller` without knowing what a controller is.
+ *
+ * Which tags arrive is the compiler's boundary, not a list kept here: these are
+ * the tags the parser had no meaning for. A known tag — `@param`, `@returns`,
+ * `@deprecated` — has its own shape and its own meaning and is not one of
+ * these.
+ *
+ * The parser also decides where a tag begins, and that decision is reported
+ * rather than second-guessed. TypeScript opens a tag at an `@` wherever it sits
+ * inside a documentation block, so a tag name written mid-sentence arrives here
+ * as a tag, while a `//` comment is not documentation and contributes nothing at
+ * all. A convention that wants the stricter rule enforces it in its own linter,
+ * where the author gets a diagnostic; the graph reports what the compiler
+ * parsed.
+ */
+export interface ITtscGraphDocTag {
+  /** The tag name without its `@`: `evidence`, `evidenceExclude`, `reference`. */
+  name: string;
+
+  /**
+   * Everything written after the tag name, joined into one line.
+   *
+   * An inline link keeps the braced form it was written in (`{@link ISale}`),
+   * so a consumer matching a citation target sees what the author typed. The
+   * same link is separately a resolved edge on the node, which is what says
+   * *which* `ISale` — a name can be declared twice and only the checker knows.
+   *
+   * Absent when the tag carries no text.
+   */
+  text?: string;
+}

package/src/structures/ITtscGraphDump.ts

@@ -16,7 +16,7 @@ import { TtscGraphDumpNodeKind } from "./TtscGraphDumpNodeKind";
  * the same dump.
  *
  * `project` is the producer-local absolute locator. Every identity-bearing path
- * uses one schema-v6 coordinate relative to it: project files are ordinary
+ * uses one portable coordinate relative to it: project files are ordinary
  * relative paths; same-filesystem siblings use `../` segments; package files
  * keep their full resolution context (including version/peer-store segments);
  * and a virtual compiler source stays `bundled:///…`. Raw absolute identities
@@ -76,8 +76,8 @@ export namespace ITtscGraphDump {
      * 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
+     * The known members are `universe`, `sourceDigests`, `diskDigests`,
+     * `diagnostics`, and `docTags`. 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
@@ -88,6 +88,17 @@ export namespace ITtscGraphDump {
     /** What built the snapshot. */
     producer: IProducer;
 
+    /**
+     * The second producer behind the artifact nodes, absent when the dump
+     * carries none.
+     *
+     * Every other fact in this dump came from one Program. These did not: a
+     * plugin parsed documents that Program never read, in a process of its own.
+     * Saying so is what keeps the one-generation contract honest instead of
+     * letting an overlay ride the same claim as the compiler's facts.
+     */
+    artifactProducer?: IProducer;
+
     /** The inputs that decide which files are in the program at all. */
     universe: IUniverse;
 
@@ -233,9 +244,19 @@ export namespace ITtscGraphDump {
     ITtscGraphNode,
     "evidence" | "implementation" | "kind"
   > {
-    /** Declaration kind written by the native producer. */
+    /** Node kind written by the native producer. */
     kind: TtscGraphDumpNodeKind;
 
+    /**
+     * The artifact containing this one, by id.
+     *
+     * Present only on an artifact node: a declaration's containment is
+     * synthesized by the memory layer, and two producers of one relation would
+     * put two answers in the graph. Absent at the top of a chain, and absent
+     * rather than invented when the parent was not published.
+     */
+    parent?: string;
+
     /** Declaration span; its file is this node's `file`. */
     evidence?: ITtscGraphSpan;
 

package/src/structures/ITtscGraphLookup.ts

@@ -1,4 +1,5 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
+import { ITtscGraphDocTag } from "./ITtscGraphDocTag";
 
 /** Targeted symbol lookup when a concrete name or handle is being resolved. */
 export interface ITtscGraphLookup {
@@ -7,6 +8,19 @@ export interface ITtscGraphLookup {
 
   /** Ranked symbol matches for the query. */
   hits: ITtscGraphLookup.IHit[];
+
+  /**
+   * True when a match was left out by the limit.
+   *
+   * The audit for the ranked operations already tells a reader that
+   * `truncated` marks where more was left out, and this result had no such
+   * field — so a cut looked exactly like a complete answer. That is tolerable
+   * for a name query, where the ranking is a shortlist by design, and it is not
+   * for a documentation target: those hits are an exact match on an address, so
+   * a caller asking which code implements a specification is owed the fact that
+   * it did not get all of it.
+   */
+  truncated?: boolean;
 }
 export namespace ITtscGraphLookup {
   /** Find a concrete class, method, function, property, type, or dotted handle. */
@@ -19,6 +33,14 @@ export namespace ITtscGraphLookup {
      * short phrase (`request handler`). Exact names are not required, but this
      * is not a second broad entrypoints call; use it for a missing or ambiguous
      * named handle.
+     *
+     * It also answers the other direction. Give it a documentation target — a
+     * document section (`docs/pricing.md#sale`), an API operation
+     * (`POST:/orders`), a data model (`prisma:Sale`) — and the hits are the
+     * declarations whose documentation cites it, each carrying the tag that
+     * matched. That is the question a repository-wide search would otherwise
+     * answer, so it is worth asking here first; a target is matched exactly, so
+     * spell it as the code does.
      */
     query: string;
 
@@ -63,6 +85,15 @@ export namespace ITtscGraphLookup {
     /** Decorators written on this declaration, when any. */
     decorators?: ITtscGraphDecorator[];
 
+    /**
+     * The documentation tags that matched the query, when the query named one.
+     *
+     * Present only on a hit found through its tags, so it says why this
+     * declaration is here: the query named a specification and this is the code
+     * that answers to it. A hit matched by name carries none.
+     */
+    docTags?: ITtscGraphDocTag[];
+
     /** Relative relevance; higher is a better match. */
     score: number;
   }

package/src/structures/ITtscGraphNode.ts

@@ -1,4 +1,5 @@
 import { ITtscGraphDecorator } from "./ITtscGraphDecorator";
+import { ITtscGraphDocTag } from "./ITtscGraphDocTag";
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
 import { TtscGraphNodeKind } from "./TtscGraphNodeKind";
 import { TtscGraphNodeModifier } from "./TtscGraphNodeModifier";
@@ -18,6 +19,17 @@ export interface ITtscGraphNode {
   /** What this node represents. */
   kind: TtscGraphNodeKind;
 
+  /**
+   * The artifact containing this one, by id.
+   *
+   * Present only on an artifact node — a section's document or enclosing
+   * section, a column's model. A declaration's containment is synthesized by
+   * the memory layer from its owner and its file, which an artifact has no
+   * equivalent of: a Prisma model has no file in its address, and an API
+   * operation has no file at all.
+   */
+  parent?: string;
+
   /** The simple, unqualified declared name (`create`, `OrderService`, `App`). */
   name: string;
 
@@ -105,6 +117,21 @@ export interface ITtscGraphNode {
    */
   decorators?: ITtscGraphDecorator[];
 
+  /**
+   * Documentation tags TypeScript does not recognize, in source order: raw
+   * facts (`@evidence docs/pricing.md#sale`, `@reference …`) a consumer
+   * interprets without re-parsing source.
+   *
+   * This is where a declaration says what outside the type system it answers
+   * to, and it is the only place the graph holds it: the other end of such a
+   * relation is a document section or an API operation, which is not a node.
+   *
+   * Read it only when `provenance.capabilities` lists `docTags`. Without that
+   * claim the field is absent because the producer never looked, which is a
+   * different fact from a declaration that carries none.
+   */
+  docTags?: ITtscGraphDocTag[];
+
   /**
    * The declaration head, cut by the producer where the compiler says the body
    * opens.

package/src/structures/TtscGraphArtifactNodeKind.ts

@@ -0,0 +1,35 @@
+import type { TtscGraphNodeKind } from "./TtscGraphNodeKind";
+
+/**
+ * The node kinds that are published artifacts rather than TypeScript
+ * declarations.
+ *
+ * A citation whose target is a TypeScript symbol is a relation the checker
+ * resolved. A citation whose target is a document section, a data model field,
+ * or an API operation is one of these: a plugin parsed the artifact and
+ * published what it is, and the graph indexes that without interpreting any of
+ * it. What the linter decided about the citation — covered, excluded, missing —
+ * never travels; that is its product and it delivers it as a compile error.
+ */
+export const TTSC_GRAPH_ARTIFACT_NODE_KINDS = [
+  "markdown_document",
+  "markdown_section",
+  "prisma_model",
+  "prisma_column",
+  "prisma_relation",
+  "swagger_operation",
+] as const satisfies readonly TtscGraphNodeKind[];
+
+/**
+ * Whether a node kind names a published artifact.
+ *
+ * It is the gate an id parser needs. An artifact's id is the address a citation
+ * writes — `docs/sale.md#pricing`, `prisma:Sale.price`, `POST:/orders` — and
+ * none of those follow the `path#qualifiedName:kind` grammar
+ * {@link TtscGraphNodeId} assumes: a Prisma address carries no path because a
+ * model name is unique across the schema folder, and an operation has no file
+ * at all.
+ */
+export function isArtifactNodeKind(kind: string): boolean {
+  return (TTSC_GRAPH_ARTIFACT_NODE_KINDS as readonly string[]).includes(kind);
+}

package/src/structures/TtscGraphDumpEdgeKind.ts

@@ -5,6 +5,7 @@ export type TtscGraphDumpEdgeKind =
   | "accesses"
   | "instantiates"
   | "type_ref"
+  | "doc_ref"
   | "extends"
   | "implements"
   | "overrides"

package/src/structures/TtscGraphDumpNodeKind.ts

@@ -1,4 +1,12 @@
-/** Declaration kinds the native Go dump producer can write. */
+/**
+ * Node kinds the native Go dump producer can write.
+ *
+ * The last six are not declarations. A plugin materialized them from a Markdown
+ * document, a Prisma schema, or an API document — artifacts a citation can name
+ * that the type system holds nothing for — and their ids are the address a
+ * citation writes rather than the `path#name:kind` grammar, which is why an id
+ * is parsed only after its kind says it can be.
+ */
 export type TtscGraphDumpNodeKind =
   | "module"
   | "function"
@@ -7,4 +15,10 @@ export type TtscGraphDumpNodeKind =
   | "type"
   | "enum"
   | "variable"
-  | "method";
+  | "method"
+  | "markdown_document"
+  | "markdown_section"
+  | "prisma_model"
+  | "prisma_column"
+  | "prisma_relation"
+  | "swagger_operation";

package/src/structures/TtscGraphEdgeKind.ts

@@ -8,6 +8,13 @@
  * — `renders` is a JSX component use. Decorators are facts on their target node,
  * not edges.
  *
+ * `doc_ref` is a declaration's own documentation naming a symbol through an
+ * inline link. The checker resolves that name and counts it as a use, so it is
+ * a compiler fact like the rest; it is its own kind rather than a `type_ref`
+ * because a link is not a type position and may name a function. The tag around
+ * a link decides nothing — one under `@evidence`, under `@see`, and in ordinary
+ * prose are one relation.
+ *
  * `dispatches` is the runtime counterpart of `overrides`/`implements`: the
  * checker resolves a call to the declaration it names, and where that
  * declaration is abstract or an interface member, the code that runs is its
@@ -22,6 +29,7 @@ export type TtscGraphEdgeKind =
   | "accesses"
   | "instantiates"
   | "type_ref"
+  | "doc_ref"
   | "extends"
   | "implements"
   | "overrides"

package/src/structures/TtscGraphNodeKind.ts

@@ -17,4 +17,10 @@ export type TtscGraphNodeKind =
   | "enum"
   | "variable"
   | "method"
-  | "property";
+  | "property"
+  | "markdown_document"
+  | "markdown_section"
+  | "prisma_model"
+  | "prisma_column"
+  | "prisma_relation"
+  | "swagger_operation";

package/src/structures/index.ts

@@ -6,6 +6,7 @@
 
 export * from "./ITtscGraphApplication";
 export * from "./ITtscGraphDecorator";
+export * from "./ITtscGraphDocTag";
 export * from "./ITtscGraphDump";
 export * from "./ITtscGraphEdge";
 export * from "./ITtscGraphEvidence";
@@ -23,5 +24,6 @@ export * from "./ITtscGraphTour";
 export * from "./TtscGraphEdgeKind";
 export * from "./TtscGraphDumpEdgeKind";
 export * from "./TtscGraphDumpNodeKind";
+export * from "./TtscGraphArtifactNodeKind";
 export * from "./TtscGraphNodeKind";
 export * from "./TtscGraphNodeModifier";

package/src/view.ts

@@ -10,6 +10,7 @@ import {
   projectOptions,
 } from "./launcherArgs";
 import { parseDump } from "./model/loadGraph";
+import { publishArtifacts } from "./model/publishedArtifacts";
 import { captureProcessOutput, ensureExecutable } from "./nativeExecutable";
 import { reduce } from "./reduce";
 import { resolveGraphBinary } from "./resolveGraphBinary";
@@ -76,9 +77,24 @@ export function runView(argv: readonly string[]): number | void {
   let dumpStdout: string;
   let dumpStderr: string;
   try {
+    // The same artifacts the dump, the loader, and the resident session ask
+    // for. Without this the viewer draws a different graph from the one every
+    // other entry point answers with — and it already carries the colours for
+    // the nodes it would be missing.
+    const artifacts = publishArtifacts({
+      cwd: opts.cwd,
+      tsconfig: opts.tsconfig,
+    });
     dump = spawnSync(
       binary,
-      ["dump", "--cwd", opts.cwd, "--tsconfig", opts.tsconfig],
+      [
+        "dump",
+        "--cwd",
+        opts.cwd,
+        "--tsconfig",
+        opts.tsconfig,
+        ...(artifacts.file === null ? [] : ["--artifacts", artifacts.file]),
+      ],
       {
         stdio: ["ignore", capture.stdoutFd, capture.stderrFd],
         windowsHide: true,

package/src/viewer/index.html

@@ -102,19 +102,11 @@
         <span id="counts"></span>
       </header>
       <div id="graph"></div>
-      <footer>
-        <span class="dot"
-          ><span class="swatch" style="background: #3fb950"></span
-          >value-call</span
-        >
-        <span class="dot"
-          ><span class="swatch" style="background: #f5b042"></span
-          >type-ref</span
-        >
-        <span class="dot"
-          ><span class="swatch" style="background: #6ea8ff"></span
-          >heritage</span
-        >
+      <!-- The edge-family swatches are prepended here from the one colour map
+           in legend.ts. They used to be written out by hand, so a new family
+           rendered in the graph with no entry beside it until someone opened
+           both files. -->
+      <footer id="legend">
         <span>node size = connection count · color = declaration kind</span>
       </footer>
     </div>