@ttsc/graph 0.16.6 → 0.16.7

package/src/server/instructions.ts

@@ -4,73 +4,85 @@
  * files. Keep it short; the per-tool descriptions carry the detail.
  */
 export const instructions = `
-Before answering a TypeScript codebase question, call query. It is the
-code-evidence path:
-symbols, dependency paths, edge evidence ranges, and sourceSpan line anchors
-from the resident project graph. Do not answer from assumptions, ls, rg, cat,
-or Get-Content when graph evidence can answer the code question.
-
-The graph is a resident TypeScript fact map, not an answer writer. Fill
-arguments in order: question, graphNeed, draft, review, request. Write
-draft.reason before draft.type, review it for overfetch and non-graph fallback,
-then choose one final request.type:
-entrypoints, lookup, trace, details, overview, or escape. If the review shows the
-question is about scripts, config, generated output, prose docs, or evidence
-already in hand, choose escape instead of spending a graph
-operation. If more TypeScript evidence is needed, make another graph request
-instead of switching to shell search.
-
-Budget graph calls before the first request. Most answers need 1-3 calls, and
-four calls is the hard stop for one answer. A fifth graph call means the tool is
-being used as a source reader; answer from returned handles/ranges or choose
-escape and report the missing span.
-
-For behavior, lifecycle, request-flow, rendering-flow, or validation-flow
-questions, start with one default entrypoints call, then one trace from the best
-handle, then answer. Use overview only for broad architecture or public API
-orientation.
-
-The graph already knows resolved symbols, dependency edges, evidence spans,
-decorators, stable handles, and sourceSpan line anchors. Use returned ranges and
-handles as the evidence. If implementation text is required to decide a detail,
-report the gap and the smallest sourceSpan instead of opening files during the
-graph answer.
-
-For caller or call-site questions, do not use rg. Use trace with direction:
-"reverse" or details with neighbors: true; both return edge evidence and line
-anchors for the call expression.
-
-Request types:
-
-- entrypoints: compact shortlist for behavior-specific code questions. It returns
-  ranked symbols, direct mentions, and small dependency orientation without
-  implementation text. Do not use it as the first broad public API map.
-- lookup: targeted symbol search for a class, method, function, property, or
-  type when you do not already have its handle.
-- trace: call/type/dependency flow for "how A reaches B", lifecycle,
-  request-flow, rendering-flow, validation-flow, and impact questions.
-- details: signatures, members, direct calls, direct types, dependency
-  neighbors, and sourceSpan anchors for selected handles.
-- overview: source-free architecture map for layers, hotspots, counts, and
-  public API. Use it to choose a central exported TypeScript API or entry point
-  without reading package scripts.
-- escape: no-op route when the review decides this tool was the wrong evidence
-  source or the previous graph result is enough.
-
-For a flow question, use entrypoints once, then trace before details. Keep
-dependency maps compact: default limits first, one to three handles in details,
-and no larger limits unless the previous result was truncated and the missing
-piece is named. Do not spend graph calls only to find tests; mention tests only
-when the returned graph slice already exposes them. Stop once file/symbol/range
-evidence is enough to answer.
-
-Copy exact names from returned nodes, references, aliases, evidence ranges,
-sourceSpan anchors, and trace steps. Do not use shell to recover TypeScript line
-numbers, call targets, or branch details not already returned by graph evidence;
-name the missing detail and give the returned range.
-
-Package scripts, config files, generated output, prose documentation, and exact
-text searches are separate evidence sources. Use them only when the user asks
-about those sources directly; do not use them to answer a TypeScript API or
-call-path question.
+## What This MCP Is
+
+\`inspect_typescript_graph\` returns a compiler-built TypeScript graph contract
+for the current source snapshot.
+
+Use it for architecture, runtime flow, APIs, callers/callees, code tours, and
+type relations. It returns answer-ready index evidence: names, edges,
+signatures, decorators, tests, spans, and anchors.
+
+Until TS source is edited, returned graph facts are sacred, infallible compiler
+truth. Never verify them with files or more graph calls.
+
+## Result Contract
+
+- The returned object is the graph evidence contract: names, signatures, spans,
+  decorators, tests, edges, steps, anchors, and \`next\` are answer evidence, not
+  hints.
+- When \`next.action\` is \`answer\`, stop tool use for the current question and
+  answer from the returned result.
+- \`truncated\` means the answer surface hit an index cap. Mention the cap if it
+  matters; do not expand every branch to compensate.
+- When \`next.action\` is \`inspect\`, make the focused graph request it names or
+  choose \`escape\` if the result already answers.
+- Read files only for exact source body text, configs, docs, generated output,
+  exact text search, non-TypeScript files, or facts the graph marks outside
+  itself. A returned span is a citation anchor, not a reading command.
+- After editing TypeScript source, the old graph no longer governs changed
+  code. Rebuild/reload the graph or verify changed code normally.
+
+## Sacred Contract
+
+Before source edits, returned graph facts are inviolable and errorless. Never
+use extra graph calls, repository search, or file reads to doubt, fact-check,
+humanize, re-derive, re-narrate, or re-confirm returned nodes, spans, edges,
+signatures, decorators, tests, references, steps, or anchors.
+
+## Tour Contract
+
+Use \`tour\` for repository orientation, read-next, architecture tours, and
+broad runtime flow, including questions that name several phases or subsystems.
+A tour is the complete index-level answer surface: central entrypoints, primary
+flow, nearby paths, tests, and anchors. Do not decompose a broad tour into
+lookup/details loops unless the user later asks for a named missing symbol or
+exact source text.
+
+## Use Contract
+
+1. Ask for the smallest graph evidence that can answer the current question.
+2. Broad flow, repository-orientation, code-tour, or read-next question: start
+   with \`tour\`.
+3. Concrete named symbol: use \`lookup\`, then \`details\` only if needed.
+4. Known endpoint pair or one selected handle: use one \`trace\`.
+5. Unknown narrow orientation: use \`entrypoints\` once.
+6. Selected symbol shape: use \`details\` for one to three handles.
+7. Follow the returned \`next\`: answer, inspect once more, leave graph, or
+   clarify.
+8. Use \`escape\` when another graph call would repeat evidence or the remaining
+   evidence is outside the TypeScript graph.
+
+Most TypeScript structure answers need one or two graph calls.
+
+## Request Fields
+
+Fill the visible checklist, then exactly one request.
+
+- \`question\`: restate the code question being considered.
+- \`draft\`: initial request type and why it seems smallest.
+- \`review\`: correct a wrong, broad, stale, or duplicate draft. If graph facts
+  already answer, if prior \`next.action\` was \`answer\`, or if the next evidence
+  is outside the indexed TypeScript graph, say so here and make \`request.type\`
+  be \`escape\`. If a broad flow draft is not \`tour\`, correct it here.
+- \`request\`: final request after review.
+
+## How to answer from graph evidence
+
+- Use returned node names, signatures, edges, references, evidence, and
+  \`sourceSpan\` ranges directly.
+- Explain the central path first, then mention important branches.
+- For tests, impact, or reading lists, returned nodes and ranges are the answer
+  evidence, not search keywords.
+- A returned range is a sacred citation anchor, not permission to open the file.
 `.trim();

package/src/server/pathPolicy.ts

@@ -0,0 +1,43 @@
+import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+
+/** True for dependency declarations outside the authored project graph. */
+export function isExternalNode(node: ITtscGraphNode): boolean {
+  return (
+    node.external ||
+    node.file.startsWith("bundled://") ||
+    /(^|\/)node_modules\//.test(node.file)
+  );
+}
+
+/** True for tests, examples, fixtures, generated output, and build artifacts. */
+export function isSupportPath(file: string): boolean {
+  return (
+    file === "" ||
+    file.startsWith("bundled://") ||
+    /(^|\/)node_modules\//.test(file) ||
+    /(^|\/)(test|tests|__tests__|spec|sample|samples|fixture|fixtures|__fixtures__|example|examples)\//.test(
+      file,
+    ) ||
+    /\.(test|spec)\.[cm]?tsx?$/.test(file) ||
+    /(^|\/)typings\.[cm]?ts$/.test(file) ||
+    /\.d\.[cm]?ts$/.test(file) ||
+    /(^|\/)(dist|build|coverage|generated|__generated__)\//.test(file)
+  );
+}
+
+/** True for source files whose declarations are tests or test helpers. */
+export function isTestPath(file: string): boolean {
+  return (
+    /(^|\/)(test|tests|__tests__|spec)\//.test(file) ||
+    /\.(test|spec)\.[cm]?tsx?$/.test(file)
+  );
+}
+
+/** True when exported symbols are unlikely to be authored public API. */
+export function isPublicApiNoisePath(file: string): boolean {
+  return (
+    isSupportPath(file) ||
+    /(^|\/|\.)typings\.[cm]?ts$/.test(file) ||
+    /(^|\/)internal\//.test(file)
+  );
+}

package/src/server/resultGuide.ts

@@ -0,0 +1,20 @@
+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/server/runDetails.ts

@@ -8,7 +8,9 @@ import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
 import { ITtscGraphEvidence } from "../structures/ITtscGraphEvidence";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
 import { accessAliasesFor } from "./accessAliases";
+import { isExternalNode } from "./pathPolicy";
 import { resolveGraphHandle } from "./resolveHandle";
+import { resultGuide, resultNext } from "./resultGuide";
 
 // A signature is the declaration head up to the body brace: a handful of lines.
 const MAX_SIGNATURE_LINES = 4;
@@ -19,8 +21,8 @@ const MAX_NEIGHBORS = 3;
 const DEFAULT_MEMBERS = 6;
 const MAX_MEMBERS = 8;
 // Direct dependency groups are orientation slices, not full fan-out dumps.
-const DEFAULT_DEPENDENCIES = 1;
-const MAX_DEPENDENCIES = 2;
+const DEFAULT_DEPENDENCIES = 2;
+const MAX_DEPENDENCIES = 4;
 // Object literal outlines are navigation aids, not source excerpts.
 const MAX_OBJECT_MEMBER_LINES = 300;
 // Structural relationships are navigation, not the dependency picture details is for.
@@ -58,6 +60,7 @@ export function runDetails(
     MAX_DEPENDENCIES,
   );
   const wantNeighbors = props.neighbors === true;
+  const includeExternal = props.includeExternal === true;
   const nodes: ITtscGraphDetails.INode[] = [];
   const unknown: string[] = [];
   for (const handle of props.handles) {
@@ -89,10 +92,30 @@ export function runDetails(
         endLine: span.endLine,
       };
     }
-    const calls = dependencyRefs(graph, node, executionKinds, dependencyLimit);
+    const calls = dependencyRefs(
+      graph,
+      node,
+      executionKinds,
+      dependencyLimit,
+      includeExternal,
+    );
     if (calls.length > 0) detail.calls = calls;
-    const types = dependencyRefs(graph, node, typeKinds, dependencyLimit);
+    const types = dependencyRefs(
+      graph,
+      node,
+      typeKinds,
+      dependencyLimit,
+      includeExternal,
+    );
     if (types.length > 0) detail.types = types;
+    const implementedBy = incomingDependencyRefs(
+      graph,
+      node,
+      implementationKinds,
+      dependencyLimit,
+      includeExternal,
+    );
+    if (implementedBy.length > 0) detail.implementedBy = implementedBy;
     if (CONTAINER_KINDS.has(node.kind)) {
       const list = members(graph, node, memberLimit);
       if (list.length > 0) detail.members = list;
@@ -113,17 +136,30 @@ export function runDetails(
         graph.outgoing(node.id),
         "to",
         neighborLimit,
+        includeExternal,
       );
       detail.dependedOnBy = refs(
         graph,
         graph.incoming(node.id),
         "from",
         neighborLimit,
+        includeExternal,
       );
     }
     nodes.push(detail);
   }
-  return { type: "details", nodes, unknown };
+  return {
+    type: "details",
+    nodes,
+    next: resultNext(
+      "answer",
+      "Selected signatures, members, dependencies, implementation candidates, and ranges are enough for a shape or reading-anchor answer.",
+    ),
+    guide: resultGuide(
+      "Use signatures, members, calls, types, implementedBy, literals, and sourceSpan anchors as selected symbol facts.",
+    ),
+    unknown,
+  };
 }
 
 /** The members a container owns (via `contains`), each with its own signature. */
@@ -238,12 +274,14 @@ function refs(
   edges: readonly ITtscGraphEdge[],
   end: "to" | "from",
   limit: number,
+  includeExternal: boolean,
 ): ITtscGraphDetails.IReference[] {
   const ranked: Array<{ ref: ITtscGraphDetails.IReference; rank: number }> = [];
   for (const edge of edges) {
     if (STRUCTURAL_KINDS.has(edge.kind)) continue;
     const other = graph.node(end === "to" ? edge.to : edge.from);
     if (other === undefined) continue;
+    if (!includeExternal && isExternalNode(other)) continue;
     const ref: ITtscGraphDetails.IReference = {
       id: other.id,
       name: other.qualifiedName ?? other.name,
@@ -274,18 +312,21 @@ const executionKinds = new Set([
   "renders",
 ]);
 const typeKinds = new Set(["type_ref", "extends", "implements", "overrides"]);
+const implementationKinds = new Set(["implements", "overrides"]);
 
 function dependencyRefs(
   graph: TtscGraphMemory,
   node: ITtscGraphNode,
   kinds: ReadonlySet<string>,
   limit: number,
+  includeExternal: boolean,
 ): ITtscGraphDetails.IReference[] {
   const ranked: Array<{ ref: ITtscGraphDetails.IReference; rank: number }> = [];
   for (const edge of graph.outgoing(node.id)) {
     if (!kinds.has(edge.kind)) continue;
     const other = graph.node(edge.to);
     if (other === undefined || other.kind === "file") continue;
+    if (!includeExternal && isExternalNode(other)) continue;
     const name = other.qualifiedName ?? other.name;
     const ref: ITtscGraphDetails.IReference = {
       id: other.id,
@@ -317,6 +358,49 @@ function dependencyRefs(
   return out;
 }
 
+function incomingDependencyRefs(
+  graph: TtscGraphMemory,
+  node: ITtscGraphNode,
+  kinds: ReadonlySet<string>,
+  limit: number,
+  includeExternal: boolean,
+): ITtscGraphDetails.IReference[] {
+  const ranked: Array<{ ref: ITtscGraphDetails.IReference; rank: number }> = [];
+  for (const edge of graph.incoming(node.id)) {
+    if (!kinds.has(edge.kind)) continue;
+    const other = graph.node(edge.from);
+    if (other === undefined || other.kind === "file") continue;
+    if (!includeExternal && isExternalNode(other)) continue;
+    const ref: ITtscGraphDetails.IReference = {
+      id: other.id,
+      name: other.qualifiedName ?? other.name,
+      kind: other.kind,
+      file: other.file,
+      relation: edge.kind,
+    };
+    if (other.evidence?.startLine) ref.line = other.evidence.startLine;
+    const evidence = edgeEvidenceOf(edge);
+    if (evidence !== undefined) ref.evidence = evidence;
+    const aliases = accessAliasesFor(other, edgeEvidenceTextOf(edge));
+    if (aliases !== undefined) ref.aliases = aliases;
+    ranked.push({
+      ref,
+      rank: refRank(ref, edge),
+    });
+  }
+  ranked.sort((a, b) => a.rank - b.rank);
+  const out: ITtscGraphDetails.IReference[] = [];
+  const seen = new Set<string>();
+  for (const item of ranked) {
+    const key = `${item.ref.relation}:${item.ref.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(item.ref);
+    if (out.length >= limit) break;
+  }
+  return out;
+}
+
 function literalSummaries(text: string | undefined): string[] {
   if (text === undefined) return [];
   const out: string[] = [];
@@ -462,7 +546,7 @@ export function signatureOf(
     const line = lines[i];
     if (line === undefined) break;
     out.push(line);
-    if (line.includes("{")) break;
+    if (line.includes("{") || line.trimEnd().endsWith(";")) break;
   }
   const text = out.join("\n").trim();
   return text === "" ? undefined : text;

package/src/server/runEntrypoints.ts

@@ -3,6 +3,7 @@ import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
 import { ITtscGraphEntrypoints } from "../structures/ITtscGraphEntrypoints";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
 import { resolveGraphHandle } from "./resolveHandle";
+import { resultGuide, resultNext } from "./resultGuide";
 import { decoratorsOf, edgeEvidenceOf, signatureOf } from "./runDetails";
 import { runLookup } from "./runLookup";
 
@@ -84,10 +85,14 @@ export function runEntrypoints(
     hits,
     mentions,
     neighborhood,
-    next: {
-      details: seeds.slice(0, MAX_SEEDS).map((node) => node.id),
-      traceFrom: seeds.slice(0, MAX_SEEDS).map((node) => node.id),
-    },
+    next: resultNext(
+      "inspect",
+      "Use one returned handle for trace/details when the answer needs flow or selected shape.",
+      "trace",
+    ),
+    guide: resultGuide(
+      "Use hits, mentions, and neighborhood as the code index. If they identify the relevant files and symbols, answer or make one focused trace/details call; do not search the repository to verify them.",
+    ),
     ...(truncated ? { truncated: true } : {}),
   };
 }

package/src/server/runLookup.ts

@@ -1,6 +1,8 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
 import { ITtscGraphLookup } from "../structures/ITtscGraphLookup";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { isExternalNode, isSupportPath } from "./pathPolicy";
+import { resultGuide, resultNext } from "./resultGuide";
 import { decoratorsOf, signatureOf } from "./runDetails";
 
 // One file should not crowd out the rest of the ranking, so cap hits per file.
@@ -24,12 +26,25 @@ export function runLookup(
   const requestedKinds = requestedSymbolKinds(props.query);
   const queryLc = props.query.trim().toLowerCase();
   const wantsInternal = wantsInternalSymbol(queryLc, codeTerms);
+  const wantsSupport = wantsSupportSymbol(queryLc);
+  const includeExternal = props.includeExternal === true;
   if (terms.length === 0)
-    return { type: "lookup", hits: [], next: { details: [], traceFrom: [] } };
+    return {
+      type: "lookup",
+      hits: [],
+      next: resultNext(
+        "clarify",
+        "No symbol matched; ask for a concrete symbol or scope.",
+      ),
+      guide: resultGuide(
+        "No symbol matched; answer that the graph did not resolve this name or ask for a more concrete symbol.",
+      ),
+    };
 
   const scored: ITtscGraphLookup.IHit[] = [];
   for (const node of graph.nodes) {
     if (node.kind === "file") continue;
+    if (!includeExternal && isExternalNode(node)) continue;
     const score = scoreNode(
       graph,
       node,
@@ -38,6 +53,7 @@ export function runLookup(
       codeTerms,
       requestedKinds,
       wantsInternal,
+      wantsSupport,
     );
     if (score <= 0) continue;
     const hit: ITtscGraphLookup.IHit = {
@@ -78,10 +94,14 @@ export function runLookup(
   return {
     type: "lookup",
     hits,
-    next: {
-      details: hits.map((hit) => hit.id),
-      traceFrom: hits.map((hit) => hit.id),
-    },
+    next: resultNext(
+      "inspect",
+      "Use one returned id for trace/details when the answer needs flow or shape.",
+      "details",
+    ),
+    guide: resultGuide(
+      "Use ranked hits and signatures as symbol evidence. If the target is clear, answer or make one focused trace/details call; do not search files to verify the match.",
+    ),
   };
 }
 
@@ -94,6 +114,7 @@ function scoreNode(
   codeTerms: string[],
   requestedKinds: Set<string>,
   wantsInternal: boolean,
+  wantsSupport: boolean,
 ): number {
   const name = node.name.toLowerCase();
   const qualified = (node.qualifiedName ?? node.name).toLowerCase();
@@ -148,13 +169,19 @@ function scoreNode(
   score += Math.min(8, Math.log2(1 + fan) * 2);
 
   // Dampen what is rarely the intended target.
-  if (node.external) score *= 0.5;
   if (node.ignored) score *= 0.3;
   if (isTestFile(node.file)) score *= 0.7;
+  if (!wantsSupport && isSupportPath(node.file)) score *= 0.35;
   if (!wantsInternal && isInternalish(node)) score *= 0.82;
   return score;
 }
 
+function wantsSupportSymbol(queryLc: string): boolean {
+  return /\b(test|tests|spec|fixture|fixtures|sample|samples|example|examples|generated|build|dist)\b/.test(
+    queryLc,
+  );
+}
+
 function wantsInternalSymbol(queryLc: string, codeTerms: string[]): boolean {
   return (
     /\b(internal|private|implementation|impl)\b/.test(queryLc) ||

package/src/server/runOverview.ts

@@ -1,6 +1,8 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
 import { ITtscGraphOverview } from "../structures/ITtscGraphOverview";
+import { isPublicApiNoisePath, isSupportPath } from "./pathPolicy";
+import { resultGuide, resultNext } from "./resultGuide";
 
 /** Edges that express nesting/packaging, not code dependency. */
 const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
@@ -36,6 +38,13 @@ export function runOverview(
       edges: graph.edges.length,
       byKind,
     },
+    next: resultNext(
+      "answer",
+      "Counts, layers, hotspots, and public API are sufficient for broad orientation.",
+    ),
+    guide: resultGuide(
+      "Use counts, layers, hotspots, and public API as a broad orientation map. Do not expand it into file reads unless the user needs exact source body text.",
+    ),
   };
   if (want("layers")) result.layers = layers(graph);
   if (want("hotspots")) result.hotspots = hotspots(graph);
@@ -47,7 +56,13 @@ export function runOverview(
 function layers(graph: TtscGraphMemory): ITtscGraphOverview.ILayer[] {
   const byDir = new Map<string, { files: Set<string>; exported: number }>();
   for (const node of graph.nodes) {
-    if (node.external || node.kind === "file") continue;
+    if (
+      node.external ||
+      node.ignored ||
+      node.kind === "file" ||
+      isSupportPath(node.file)
+    )
+      continue;
     const dir = dirname(node.file);
     let entry = byDir.get(dir);
     if (!entry) {
@@ -80,7 +95,13 @@ function hotspots(graph: TtscGraphMemory): ITtscGraphOverview.IHotspot[] {
     return n;
   };
   return graph.nodes
-    .filter((node) => !node.external && node.kind !== "file")
+    .filter(
+      (node) =>
+        !node.external &&
+        !node.ignored &&
+        node.kind !== "file" &&
+        !isSupportPath(node.file),
+    )
     .map((node) => ({
       ...nodeOf(node),
       fanIn: real(node.id, "in"),
@@ -137,12 +158,7 @@ function publicApi(graph: TtscGraphMemory): ITtscGraphOverview.IPublicApi[] {
  * not framework-specific; it keeps the API surface to authored, used code.
  */
 function isNoiseFile(file: string): boolean {
-  return (
-    /(^|\/)(test|tests|__tests__|spec|sample|samples)\//.test(file) ||
-    /\.(test|spec)\.[cm]?tsx?$/.test(file) ||
-    /(^|\/|\.)typings\.[cm]?ts$/.test(file) ||
-    /\.d\.[cm]?ts$/.test(file)
-  );
+  return isPublicApiNoisePath(file);
 }
 
 /** The parent directory of a project-relative path (`.` at the root). */