@ttsc/graph 0.18.3 → 0.19.0

package/src/structures/ITtscGraphTrace.ts

@@ -1,5 +1,4 @@
 import { ITtscGraphEvidence } from "./ITtscGraphEvidence";
-import { ITtscGraphNext } from "./ITtscGraphNext";
 
 /** The compact dependency or caller flow returned from a selected start symbol. */
 export interface ITtscGraphTrace {
@@ -18,99 +17,141 @@ export interface ITtscGraphTrace {
   /** Unique nodes reached (excluding the start), each with its depth and roles. */
   reached: ITtscGraphTrace.INode[];
 
-  /** True when the trace hit maxNodes or maxDepth and more flow exists. */
+  /** True when the trace hit its node or depth cap; the returned flow stands. */
   truncated: boolean;
 
   /** The resolved `to` target, when a path was requested. */
   target?: ITtscGraphTrace.INode;
 
   /**
-   * When `to` was given: the ordered dependency path from `from` to `to`
-   * (`from` first, `to` last), or empty when `to` is not reachable from
-   * `from`.
+   * Ordered dependency path from `from` to `to` when `to` was given (`from`
+   * first, `to` last), empty when `to` is unreachable.
    */
   path?: ITtscGraphTrace.INode[];
 
   /** Compact hop summaries preserving node names and edge evidence, capped. */
   steps?: string[];
 
-  /** How to use this source-free result next. */
-  next: ITtscGraphNext;
-
-  /** Human-readable compatibility note mirroring `next`. */
-  guide: string;
+  /**
+   * Symbols both ends touch, when no call path runs between them.
+   *
+   * Nothing calls across the gap because in an event-driven codebase nothing
+   * does: a handler registers a listener on an emitter, the emitter's `emit()`
+   * runs whatever a registration put in an array, and no call edge crosses that
+   * array. But both ends touch the emitter, and that is an edge, not a guess —
+   * Excalidraw's pointer handler and its store's emit both reference
+   * `Store.onDurableIncrementEmitter`, which is exactly the seam the call graph
+   * cannot walk.
+   *
+   * A junction is not a path. It is the symbol to look at next, and the edges
+   * that say why.
+   */
+  junctions?: ITtscGraphTrace.IJunction[];
 
   /** When `from` was an ambiguous name, the matches to disambiguate with. */
   candidates?: ITtscGraphTrace.INode[];
 }
 export namespace ITtscGraphTrace {
+  /** A symbol both ends of an unreachable path touch, and how each touches it. */
+  export interface IJunction {
+    /** Stable node id: trace or inspect this symbol to cross the seam. */
+    id: string;
+
+    /** Qualified symbol name when available, otherwise the simple name. */
+    name: string;
+
+    /** Declaration kind (`variable`, `method`, `class`, ...). */
+    kind: string;
+
+    /** Project-relative path of the file that declares it. */
+    file: string;
+
+    /** 1-based declaration line, when known. */
+    line?: number;
+
+    /** How the start reaches it: the edge kind, and where that edge sits. */
+    fromStart: IJunctionEdge;
+
+    /** How the target reaches it, or is reached from it. */
+    fromTarget: IJunctionEdge;
+  }
+
+  /** One edge between an end of the requested path and the junction. */
+  export interface IJunctionEdge {
+    /** `calls`, `accesses`, `instantiates`, `type_ref`, ... */
+    kind: string;
+
+    /** True when the end is the edge's source, false when it is the target. */
+    outgoing: boolean;
+
+    /** Where the reference sits in source. */
+    evidence?: ITtscGraphEvidence;
+  }
+
   /** Where and how far to trace dependency flow. */
   export interface IRequest {
     /** Discriminator for dependency tracing. */
     type: "trace";
 
     /**
-     * Where to start: a node id from another tool, a simple symbol name, or a
-     * dotted member name such as `OrderService.create`. An ambiguous name
-     * returns its candidates instead of a trace.
+     * Where to start: a node id, a simple symbol name, or a dotted member
+     * (`OrderService.create`). An ambiguous name returns its candidates instead
+     * of a trace.
      */
     from: string;
 
     /**
-     * A target symbol: node id, simple symbol name, or dotted member name. When
-     * given, the tool returns the dependency path from `from` to this target,
-     * the one-call answer for "how does A reach B", instead of an open-ended
-     * trace. Prefer this path mode whenever both ends are known.
+     * Target symbol (node id, simple name, or dotted member). When given, the
+     * tool returns the dependency path from `from` to it, the one-call answer
+     * for "how does A reach B". Prefer this path mode whenever both ends are
+     * known.
      */
     to?: string;
 
     /**
-     * `forward` follows what the start uses (callees, instantiations, renders);
-     * `reverse` follows what uses the start (callers); `impact` is a reverse
-     * trace that prioritizes public API and test nodes a change would reach.
-     * Its test nodes are semantic usage edges, not a text-search inventory.
-     * Caller questions usually fit `reverse`.
+     * Trace direction:
+     *
+     * - `forward`: what the start uses (callees, instantiations, renders)
+     * - `reverse`: what uses the start (callers); the usual fit for caller
+     *   questions
+     * - `impact`: reverse trace prioritizing public API and test nodes a change
+     *   reaches; its test nodes are semantic usage edges, not a text search
      *
      * @default "forward"
      */
     direction?: "forward" | "reverse" | "impact";
 
     /**
-     * Which non-structural edge family to follow: `execution` follows runtime
-     * calls, instantiations, property access, and JSX renders; `types` follows
-     * type references and inheritance; `all` preserves the full graph. Flow
-     * questions should usually choose `execution` rather than `all`.
+     * Non-structural edge family to follow:
+     *
+     * - `execution`: runtime calls, instantiations, property access, JSX renders
+     * - `types`: type references and inheritance
+     * - `all`: the full graph
+     *
+     * Flow questions usually want `execution`, not `all`.
      *
      * @default "all"
      */
     focus?: "all" | "execution" | "types";
 
     /**
-     * How many hops deep to follow. Open forward/reverse traces are capped at
-     * 2; impact traces at 4; path mode at 12.
-     *
-     * Prefer the default for open traces. Raise only for path mode or when the
-     * previous trace named the missing next hop.
+     * Hops deep to follow (open forward/reverse cap at 8, impact at 4, path
+     * mode at 12). Raise it to follow a runtime chain to its end in one call.
      *
-     * @default 2
+     * @default 3
      */
     maxDepth?: number;
 
     /**
-     * Cap on reached nodes; the trace stops and marks itself truncated past it.
-     * Open forward/reverse traces are capped at 8 nodes, impact at 16 nodes.
+     * Cap on reached nodes (open forward/reverse cap at 32, impact at 16).
      *
-     * Prefer the default; use larger open traces only when a named missing edge
-     * requires it.
-     *
-     * @default 6
+     * @default 12
      */
     maxNodes?: number;
 
     /**
      * Include dependency-boundary nodes from node_modules or bundled `.d.ts`
-     * libraries. Leave false for source-flow tours; enable only when the user
-     * asks about external type/API boundaries.
+     * libraries. Enable only for questions about external type/API boundaries.
      *
      * @default false
      */
@@ -131,18 +172,8 @@ export namespace ITtscGraphTrace {
     /** Hops from the start (1 = direct). */
     depth: number;
 
-    /**
-     * Source span for the expression that produced this hop. It is repository
-     * evidence for the hop and can be cited without opening the file.
-     */
+    /** Source span that produced the hop: citable without opening the file. */
     evidence?: ITtscGraphEvidence;
-
-    /**
-     * Stable access-path aliases derived from edge evidence. These preserve a
-     * resolved member's owner and the concrete property path used at the call
-     * site.
-     */
-    aliases?: string[];
   }
 
   /** A node on the trace: the start, a reached node, or a candidate. */

package/src/structures/TtscGraphEdgeKind.ts

@@ -6,6 +6,12 @@
  * `extends`, `implements`, `overrides`, `renders`) are resolved by the checker
  * — `renders` is a JSX component use. `decorates` carries a decorator fact and
  * `tests` a test-to-subject relationship.
+ *
+ * `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
+ * implementation. It carries the implementation's declaration span, and a
+ * traversal that follows what executes emits it in place of the dead end.
  */
 export type TtscGraphEdgeKind =
   | "contains"
@@ -18,6 +24,7 @@ export type TtscGraphEdgeKind =
   | "extends"
   | "implements"
   | "overrides"
+  | "dispatches"
   | "decorates"
   | "renders"
   | "tests";

package/src/structures/index.ts

@@ -6,7 +6,6 @@
 
 export * from "./ITtscGraphApplication";
 export * from "./ITtscGraphDecorator";
-export * from "./ITtscGraphDiagnostic";
 export * from "./ITtscGraphDump";
 export * from "./ITtscGraphEdge";
 export * from "./ITtscGraphEvidence";
@@ -18,6 +17,7 @@ export * from "./ITtscGraphOverview";
 export * from "./ITtscGraphLookup";
 export * from "./ITtscGraphNext";
 export * from "./ITtscGraphTrace";
+export * from "./ITtscGraphSpan";
 export * from "./ITtscGraphTour";
 export * from "./TtscGraphEdgeKind";
 export * from "./TtscGraphNodeKind";

package/src/view.ts

@@ -51,7 +51,9 @@ function parseViewArgs(argv: readonly string[]): ViewOptions {
 export function runView(argv: readonly string[]): number | void {
   const opts = parseViewArgs(argv);
 
-  const binary = resolveGraphBinary();
+  // Anchor binary resolution at the project selected by `--cwd`, so `view` from
+  // an unrelated directory still finds the `ttsc` installed under the target.
+  const binary = resolveGraphBinary(process.env, opts.cwd);
   if (binary === null) {
     process.stderr.write(
       "@ttsc/graph: could not resolve the ttscgraph binary. " +

package/lib/server/accessAliases.d.ts

@@ -1,8 +0,0 @@
-import { ITtscGraphNode } from "../structures/ITtscGraphNode";
-/**
- * Derive stable access-path aliases for a member edge from its source
- * expression. If a hop reaches `Owner.member` through `obj.path.member`, the
- * alias `Owner.path.member` keeps both the resolved owner and the concrete
- * access path visible without reopening source.
- */
-export declare function accessAliasesFor(node: ITtscGraphNode | undefined, evidenceText: string | undefined): string[] | undefined;

package/lib/server/accessAliases.js

@@ -1,53 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.accessAliasesFor = accessAliasesFor;
-/**
- * Derive stable access-path aliases for a member edge from its source
- * expression. If a hop reaches `Owner.member` through `obj.path.member`, the
- * alias `Owner.path.member` keeps both the resolved owner and the concrete
- * access path visible without reopening source.
- */
-function accessAliasesFor(node, evidenceText) {
-    if (node === undefined ||
-        node.qualifiedName === undefined ||
-        evidenceText === undefined) {
-        return undefined;
-    }
-    const segments = dottedSegments(evidenceText);
-    if (segments.length < 2 || segments[segments.length - 1] !== node.name) {
-        return undefined;
-    }
-    const dot = node.qualifiedName.lastIndexOf(".");
-    if (dot < 0)
-        return undefined;
-    const owner = node.qualifiedName.slice(0, dot);
-    const suffix = segments.slice(1).join(".");
-    const aliases = new Set();
-    for (const candidate of [...ownerDisplayAliases(owner), owner]) {
-        const alias = `${candidate}.${suffix}`;
-        if (alias !== node.qualifiedName)
-            aliases.add(alias);
-    }
-    return aliases.size > 0 ? [...aliases] : undefined;
-}
-function dottedSegments(text) {
-    const normalized = text.trim().replace(/\?\./g, ".");
-    const parts = normalized.split(".");
-    if (parts.length < 2)
-        return [];
-    return parts.every((part) => /^[A-Za-z_$][\w$]*$/.test(part)) ? parts : [];
-}
-function ownerDisplayAliases(owner) {
-    const display = owner.replace(/^_+/, "");
-    const out = new Set();
-    for (const suffix of ["Internals", "Internal"]) {
-        if (display.length > suffix.length && display.endsWith(suffix)) {
-            out.add(display.slice(0, -suffix.length));
-        }
-    }
-    if (out.size === 0 && display !== owner)
-        out.add(display);
-    out.delete(owner);
-    return [...out];
-}
-//# sourceMappingURL=accessAliases.js.map

package/lib/server/accessAliases.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"accessAliases.js","sourceRoot":"","sources":["../../src/server/accessAliases.ts"],"names":[],"mappings":";;;AAEA;;;;;GAKG;AACH,0BACE,IAAgC,EAChC,YAAgC;IAEhC,IACE,IAAI,KAAK,SAAS;QAClB,IAAI,CAAC,aAAa,KAAK,SAAS;QAChC,YAAY,KAAK,SAAS,EAC1B,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,QAAQ,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IAC9C,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QACvE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,CAAC,aAAa,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAChD,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAE9B,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,SAAS,IAAI,CAAC,GAAG,mBAAmB,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;QAC/D,MAAM,KAAK,GAAG,GAAG,SAAS,IAAI,MAAM,EAAE,CAAC;QACvC,IAAI,KAAK,KAAK,IAAI,CAAC,aAAa;YAAE,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACrD,CAAC;AAED,SAAS,cAAc,CAAC,IAAY;IAClC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;IACrD,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAC7E,CAAC;AAED,SAAS,mBAAmB,CAAC,KAAa;IACxC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,MAAM,IAAI,CAAC,WAAW,EAAE,UAAU,CAAC,EAAE,CAAC;QAC/C,IAAI,OAAO,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC/D,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,IAAI,OAAO,KAAK,KAAK;QAAE,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC1D,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClB,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;AAClB,CAAC"}

package/lib/server/resultGuide.d.ts

@@ -1,3 +0,0 @@
-import { ITtscGraphNext } from "../structures/ITtscGraphNext";
-export declare function resultGuide(action: string): string;
-export declare function resultNext(action: ITtscGraphNext["action"], reason: string, request?: ITtscGraphNext["request"]): ITtscGraphNext;

package/lib/server/resultGuide.js

@@ -1,16 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resultGuide = resultGuide;
-exports.resultNext = resultNext;
-const SOURCE_POLICY = "The returned object is the graph evidence contract: names, edges, signatures, decorators, tests, ranges, anchors, steps, and next are the answer surface. If next.action is answer, stop tool use for this question and answer now. Truncated means capped index evidence, not a request to expand every branch. Until TypeScript source is edited, returned graph facts are sacred, infallible compiler truth. Never call graph again or read files to doubt, validate, fact-check, re-derive, re-confirm, re-narrate, or improve returned graph facts. Read source bodies only when the user explicitly asks for exact source text or changed code must be verified.";
-function resultGuide(action) {
-    return `${action} ${SOURCE_POLICY}`;
-}
-function resultNext(action, reason, request) {
-    return {
-        action,
-        reason,
-        ...(request !== undefined ? { request } : {}),
-    };
-}
-//# sourceMappingURL=resultGuide.js.map

package/lib/server/resultGuide.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"resultGuide.js","sourceRoot":"","sources":["../../src/server/resultGuide.ts"],"names":[],"mappings":";;;;AAEA,MAAM,aAAa,GACjB,woBAAwoB,CAAC;AAE3oB,qBAA4B,MAAc;IACxC,OAAO,GAAG,MAAM,IAAI,aAAa,EAAE,CAAC;AACtC,CAAC;AAED,oBACE,MAAgC,EAChC,MAAc,EACd,OAAmC;IAEnC,OAAO;QACL,MAAM;QACN,MAAM;QACN,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9C,CAAC;AACJ,CAAC"}

package/lib/structures/ITtscGraphDiagnostic.d.ts

@@ -1,27 +0,0 @@
-/**
- * A compiler or plugin diagnostic, fused onto the graph so an edit-triage query
- * can name the owning symbol of an error.
- *
- * The TypeScript semantic pass contributes numeric-coded `tsc` diagnostics;
- * `@ttsc/lint` rules and transform plugins (typia, nestia, …) contribute
- * `plugin`/`lint` findings whose `code` is a string. `node` is set when the
- * finding's position was attributed to a graph node.
- */
-export interface ITtscGraphDiagnostic {
-    /** Project-relative path of the file the diagnostic is reported in. */
-    file: string;
-    /** 1-based line of the diagnostic. */
-    line: number;
-    /** 1-based column of the diagnostic, when known. */
-    column?: number;
-    /** Numeric `tsc` code, or string rule id for a lint/plugin finding. */
-    code: number | string;
-    /** The human-readable diagnostic message. */
-    message: string;
-    /** Severity, when the producer distinguishes it. */
-    severity?: "error" | "warning" | "info" | "hint";
-    /** Which lane produced the diagnostic. */
-    origin?: "tsc" | "plugin" | "lint";
-    /** Node id the diagnostic was fused onto, when resolved. */
-    node?: string;
-}

package/lib/structures/ITtscGraphDiagnostic.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ITtscGraphDiagnostic.js","sourceRoot":"","sources":["../../src/structures/ITtscGraphDiagnostic.ts"],"names":[],"mappings":""}

package/src/server/accessAliases.ts

@@ -1,55 +0,0 @@
-import { ITtscGraphNode } from "../structures/ITtscGraphNode";
-
-/**
- * Derive stable access-path aliases for a member edge from its source
- * expression. If a hop reaches `Owner.member` through `obj.path.member`, the
- * alias `Owner.path.member` keeps both the resolved owner and the concrete
- * access path visible without reopening source.
- */
-export function accessAliasesFor(
-  node: ITtscGraphNode | undefined,
-  evidenceText: string | undefined,
-): string[] | undefined {
-  if (
-    node === undefined ||
-    node.qualifiedName === undefined ||
-    evidenceText === undefined
-  ) {
-    return undefined;
-  }
-  const segments = dottedSegments(evidenceText);
-  if (segments.length < 2 || segments[segments.length - 1] !== node.name) {
-    return undefined;
-  }
-  const dot = node.qualifiedName.lastIndexOf(".");
-  if (dot < 0) return undefined;
-
-  const owner = node.qualifiedName.slice(0, dot);
-  const suffix = segments.slice(1).join(".");
-  const aliases = new Set<string>();
-  for (const candidate of [...ownerDisplayAliases(owner), owner]) {
-    const alias = `${candidate}.${suffix}`;
-    if (alias !== node.qualifiedName) aliases.add(alias);
-  }
-  return aliases.size > 0 ? [...aliases] : undefined;
-}
-
-function dottedSegments(text: string): string[] {
-  const normalized = text.trim().replace(/\?\./g, ".");
-  const parts = normalized.split(".");
-  if (parts.length < 2) return [];
-  return parts.every((part) => /^[A-Za-z_$][\w$]*$/.test(part)) ? parts : [];
-}
-
-function ownerDisplayAliases(owner: string): string[] {
-  const display = owner.replace(/^_+/, "");
-  const out = new Set<string>();
-  for (const suffix of ["Internals", "Internal"]) {
-    if (display.length > suffix.length && display.endsWith(suffix)) {
-      out.add(display.slice(0, -suffix.length));
-    }
-  }
-  if (out.size === 0 && display !== owner) out.add(display);
-  out.delete(owner);
-  return [...out];
-}

package/src/server/resultGuide.ts

@@ -1,20 +0,0 @@
-import { ITtscGraphNext } from "../structures/ITtscGraphNext";
-
-const SOURCE_POLICY =
-  "The returned object is the graph evidence contract: names, edges, signatures, decorators, tests, ranges, anchors, steps, and next are the answer surface. If next.action is answer, stop tool use for this question and answer now. Truncated means capped index evidence, not a request to expand every branch. Until TypeScript source is edited, returned graph facts are sacred, infallible compiler truth. Never call graph again or read files to doubt, validate, fact-check, re-derive, re-confirm, re-narrate, or improve returned graph facts. Read source bodies only when the user explicitly asks for exact source text or changed code must be verified.";
-
-export function resultGuide(action: string): string {
-  return `${action} ${SOURCE_POLICY}`;
-}
-
-export function resultNext(
-  action: ITtscGraphNext["action"],
-  reason: string,
-  request?: ITtscGraphNext["request"],
-): ITtscGraphNext {
-  return {
-    action,
-    reason,
-    ...(request !== undefined ? { request } : {}),
-  };
-}

package/src/structures/ITtscGraphDiagnostic.ts

@@ -1,34 +0,0 @@
-/**
- * A compiler or plugin diagnostic, fused onto the graph so an edit-triage query
- * can name the owning symbol of an error.
- *
- * The TypeScript semantic pass contributes numeric-coded `tsc` diagnostics;
- * `@ttsc/lint` rules and transform plugins (typia, nestia, …) contribute
- * `plugin`/`lint` findings whose `code` is a string. `node` is set when the
- * finding's position was attributed to a graph node.
- */
-export interface ITtscGraphDiagnostic {
-  /** Project-relative path of the file the diagnostic is reported in. */
-  file: string;
-
-  /** 1-based line of the diagnostic. */
-  line: number;
-
-  /** 1-based column of the diagnostic, when known. */
-  column?: number;
-
-  /** Numeric `tsc` code, or string rule id for a lint/plugin finding. */
-  code: number | string;
-
-  /** The human-readable diagnostic message. */
-  message: string;
-
-  /** Severity, when the producer distinguishes it. */
-  severity?: "error" | "warning" | "info" | "hint";
-
-  /** Which lane produced the diagnostic. */
-  origin?: "tsc" | "plugin" | "lint";
-
-  /** Node id the diagnostic was fused onto, when resolved. */
-  node?: string;
-}