@ttsc/graph 0.16.5 → 0.16.6

package/src/server/{runIndex.ts → runEntrypoints.ts}

@@ -1,28 +1,28 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
 import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
-import { ITtscGraphIndex } from "../structures/ITtscGraphIndex";
+import { ITtscGraphEntrypoints } from "../structures/ITtscGraphEntrypoints";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
 import { resolveGraphHandle } from "./resolveHandle";
-import { signatureOf } from "./runExpand";
-import { runQuery } from "./runQuery";
-
-const DEFAULT_LIMIT = 8;
-const MAX_LIMIT = 20;
-const DEFAULT_NEIGHBORS = 4;
-const MAX_NEIGHBORS = 8;
-const MAX_SEEDS = 6;
+import { decoratorsOf, edgeEvidenceOf, signatureOf } from "./runDetails";
+import { runLookup } from "./runLookup";
+
+const DEFAULT_LIMIT = 4;
+const MAX_LIMIT = 8;
+const DEFAULT_NEIGHBORS = 0;
+const MAX_NEIGHBORS = 2;
+const MAX_SEEDS = 3;
 const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
 
 /**
- * Build the first source-free index for a code question. The result gives the
- * model stable handles, declaration signatures, and direct graph context. It is
- * deliberately not a source reader; source remains opt-in through
- * graph_expand.
+ * Build the first source-free entrypoints list for a code question. The result
+ * gives the model stable handles, declaration signatures, and direct graph
+ * context. It is deliberately not a source reader; details adds selected symbol
+ * shape and ranges, not implementation text.
  */
-export function runIndex(
+export function runEntrypoints(
   graph: TtscGraphMemory,
-  props: ITtscGraphIndex.IProps,
-): ITtscGraphIndex {
+  props: ITtscGraphEntrypoints.IRequest,
+): ITtscGraphEntrypoints {
   const query = props.query.trim();
   const limit = bound(props.limit, DEFAULT_LIMIT, 1, MAX_LIMIT);
   const neighborLimit = bound(
@@ -32,12 +32,12 @@ export function runIndex(
     MAX_NEIGHBORS,
   );
 
-  const queryResult = runQuery(graph, { query, limit });
-  const hits = queryResult.hits.map((hit) => ({ ...hit }));
+  const lookupResult = runLookup(graph, { type: "lookup", query, limit });
+  const hits = lookupResult.hits.map((hit) => ({ ...hit }));
 
-  const mentions = directMentions(query).map((handle) => {
+  const mentions = directMentions(graph, query).map((handle) => {
     const resolved = resolveGraphHandle(graph, handle, 6);
-    const mention: ITtscGraphIndex.IMention = { handle };
+    const mention: ITtscGraphEntrypoints.IMention = { handle };
     if (resolved.node !== undefined)
       mention.node = nodeOf(graph, resolved.node);
     if (resolved.candidates !== undefined) {
@@ -61,7 +61,7 @@ export function runIndex(
   for (const hit of hits) addSeed(graph.node(hit.id));
 
   let truncated = seeds.length > MAX_SEEDS;
-  const neighborhood: ITtscGraphIndex.INeighborhood[] = [];
+  const neighborhood: ITtscGraphEntrypoints.INeighborhood[] = [];
   for (const seed of seeds.slice(0, MAX_SEEDS)) {
     const outgoing = refs(graph, graph.outgoing(seed.id), "to", neighborLimit);
     const incoming = refs(
@@ -79,15 +79,14 @@ export function runIndex(
   }
 
   return {
+    type: "entrypoints",
     query,
     hits,
     mentions,
     neighborhood,
     next: {
-      expand: seeds.slice(0, MAX_SEEDS).map((node) => node.id),
-      traceFrom: mentions
-        .map((mention) => mention.node?.id)
-        .filter((id): id is string => id !== undefined),
+      details: seeds.slice(0, MAX_SEEDS).map((node) => node.id),
+      traceFrom: seeds.slice(0, MAX_SEEDS).map((node) => node.id),
     },
     ...(truncated ? { truncated: true } : {}),
   };
@@ -96,8 +95,8 @@ export function runIndex(
 function nodeOf(
   graph: TtscGraphMemory,
   node: ITtscGraphNode,
-): ITtscGraphIndex.INode {
-  const out: ITtscGraphIndex.INode = {
+): ITtscGraphEntrypoints.INode {
+  const out: ITtscGraphEntrypoints.INode = {
     id: node.id,
     name: node.qualifiedName ?? node.name,
     kind: node.kind,
@@ -107,14 +106,16 @@ function nodeOf(
     out.line = node.evidence.startLine;
   const signature = signatureOf(graph.project, node);
   if (signature !== undefined) out.signature = signature;
+  const decorators = decoratorsOf(node);
+  if (decorators !== undefined) out.decorators = decorators;
   return out;
 }
 
 function refOf(
   node: ITtscGraphNode,
   edge: ITtscGraphEdge,
-): ITtscGraphIndex.IReference {
-  const out: ITtscGraphIndex.IReference = {
+): ITtscGraphEntrypoints.IReference {
+  const out: ITtscGraphEntrypoints.IReference = {
     id: node.id,
     name: node.qualifiedName ?? node.name,
     kind: node.kind,
@@ -123,6 +124,8 @@ function refOf(
   };
   if (node.evidence?.startLine !== undefined)
     out.line = node.evidence.startLine;
+  const evidence = edgeEvidenceOf(edge);
+  if (evidence !== undefined) out.evidence = evidence;
   return out;
 }
 
@@ -131,8 +134,9 @@ function refs(
   edges: readonly ITtscGraphEdge[],
   end: "to" | "from",
   limit: number,
-): { items: ITtscGraphIndex.IReference[]; truncated: boolean } {
-  const items: ITtscGraphIndex.IReference[] = [];
+): { items: ITtscGraphEntrypoints.IReference[]; truncated: boolean } {
+  const ranked: Array<{ ref: ITtscGraphEntrypoints.IReference; rank: number }> =
+    [];
   const seen = new Set<string>();
   let available = 0;
   for (const edge of edges) {
@@ -143,15 +147,74 @@ function refs(
     if (seen.has(key)) continue;
     seen.add(key);
     available++;
-    if (items.length < limit) items.push(refOf(other, edge));
+    const ref = refOf(other, edge);
+    ranked.push({ ref, rank: refRank(ref, edge) });
+  }
+  ranked.sort((a, b) => a.rank - b.rank);
+  const items: ITtscGraphEntrypoints.IReference[] = [];
+  for (const item of ranked) {
+    if (items.length < limit) items.push(item.ref);
   }
   return { items, truncated: available > items.length };
 }
 
-function directMentions(query: string): string[] {
+function refRank(
+  ref: ITtscGraphEntrypoints.IReference,
+  edge: ITtscGraphEdge,
+): number {
+  return (
+    edgeKindRank(edge.kind) * 100_000 +
+    evidenceRank(edge) +
+    (ref.file.startsWith("bundled://") ? 20_000 : 0)
+  );
+}
+
+function evidenceRank(edge: ITtscGraphEdge): number {
+  const line = edge.evidence?.startLine ?? 9_999;
+  const col = edge.evidence?.startCol ?? 999;
+  return line * 100 + col;
+}
+
+function edgeKindRank(kind: string): number {
+  switch (kind) {
+    case "calls":
+      return 0;
+    case "instantiates":
+      return 1;
+    case "accesses":
+    case "renders":
+      return 2;
+    case "tests":
+      return 3;
+    case "overrides":
+    case "decorates":
+      return 4;
+    case "extends":
+    case "implements":
+      return 5;
+    case "type_ref":
+      return 6;
+    default:
+      return 10;
+  }
+}
+
+function directMentions(graph: TtscGraphMemory, query: string): string[] {
   const handles = new Set<string>();
+  for (const token of query.split(/\s+/)) {
+    const handle = normalizeNodeIdToken(token);
+    if (handle !== undefined && graph.node(handle) !== undefined) {
+      handles.add(handle);
+    }
+  }
   for (const match of query.matchAll(/`([^`]+)`/g)) {
-    const handle = normalizeHandle(match[1] ?? "");
+    const raw = match[1] ?? "";
+    const id = normalizeNodeIdToken(raw);
+    if (id !== undefined && graph.node(id) !== undefined) {
+      handles.add(id);
+      continue;
+    }
+    const handle = normalizeHandle(raw);
     if (handle !== undefined) handles.add(handle);
   }
   for (const match of query.matchAll(
@@ -163,6 +226,18 @@ function directMentions(query: string): string[] {
   return [...handles];
 }
 
+function normalizeNodeIdToken(raw: string): string | undefined {
+  const value = raw
+    .trim()
+    .replace(/^[`"'([{]+/, "")
+    .replace(/[`"',.;:)\]}]+$/, "");
+  return /^[^\s#]+#[^\s#]+:(class|interface|type|enum|function|method|variable|property)$/.test(
+    value,
+  )
+    ? value
+    : undefined;
+}
+
 function normalizeHandle(raw: string): string | undefined {
   const value = raw.trim();
   return /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(value)

package/src/server/{runQuery.ts → runLookup.ts}

@@ -1,11 +1,12 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { ITtscGraphLookup } from "../structures/ITtscGraphLookup";
 import { ITtscGraphNode } from "../structures/ITtscGraphNode";
-import { ITtscGraphQuery } from "../structures/ITtscGraphQuery";
-import { signatureOf } from "./runExpand";
+import { decoratorsOf, signatureOf } from "./runDetails";
 
 // One file should not crowd out the rest of the ranking, so cap hits per file.
 const PER_FILE = 3;
-const DEFAULT_LIMIT = 12;
+const DEFAULT_LIMIT = 5;
+const MAX_LIMIT = 6;
 
 /**
  * Rank the graph's symbols against a natural query. Scoring blends exact and
@@ -14,35 +15,50 @@ const DEFAULT_LIMIT = 12;
  * nodes and caps per file so the result is a diverse, relevant shortlist rather
  * than one file's roster.
  */
-export function runQuery(
+export function runLookup(
   graph: TtscGraphMemory,
-  props: ITtscGraphQuery.IProps,
-): ITtscGraphQuery {
+  props: ITtscGraphLookup.IRequest,
+): ITtscGraphLookup {
   const terms = subwords(props.query);
+  const codeTerms = exactCodeTerms(props.query);
+  const requestedKinds = requestedSymbolKinds(props.query);
   const queryLc = props.query.trim().toLowerCase();
-  if (terms.length === 0) return { hits: [], next: { expand: [] } };
+  const wantsInternal = wantsInternalSymbol(queryLc, codeTerms);
+  if (terms.length === 0)
+    return { type: "lookup", hits: [], next: { details: [], traceFrom: [] } };
 
-  const scored: ITtscGraphQuery.IHit[] = [];
+  const scored: ITtscGraphLookup.IHit[] = [];
   for (const node of graph.nodes) {
     if (node.kind === "file") continue;
-    const score = scoreNode(graph, node, queryLc, terms);
+    const score = scoreNode(
+      graph,
+      node,
+      queryLc,
+      terms,
+      codeTerms,
+      requestedKinds,
+      wantsInternal,
+    );
     if (score <= 0) continue;
-    scored.push({
+    const hit: ITtscGraphLookup.IHit = {
       id: node.id,
       name: node.qualifiedName ?? node.name,
       kind: node.kind,
       file: node.file,
       line: node.evidence?.startLine,
       score: Math.round(score),
-    });
+    };
+    const decorators = decoratorsOf(node);
+    if (decorators !== undefined) hit.decorators = decorators;
+    scored.push(hit);
   }
 
   scored.sort((a, b) => b.score - a.score);
 
   // Diversity: keep at most PER_FILE hits per file while filling up to the limit.
-  const limit = Math.max(1, props.limit ?? DEFAULT_LIMIT);
+  const limit = bound(props.limit, DEFAULT_LIMIT, 1, MAX_LIMIT);
   const perFile = new Map<string, number>();
-  const hits: ITtscGraphQuery.IHit[] = [];
+  const hits: ITtscGraphLookup.IHit[] = [];
   for (const hit of scored) {
     const used = perFile.get(hit.file) ?? 0;
     if (used >= PER_FILE) continue;
@@ -51,15 +67,22 @@ export function runQuery(
     if (hits.length >= limit) break;
   }
 
-  // Attach each kept hit's signature — only the shortlist, so the read cost is
-  // bounded — so the model can often answer from the query alone, no expand.
+  // Attach each kept hit's signature only for the shortlist, so the model can
+  // often answer from lookup alone without a details call.
   for (const hit of hits) {
     const node = graph.node(hit.id);
     if (node === undefined) continue;
     const sig = signatureOf(graph.project, node);
     if (sig !== undefined) hit.signature = sig;
   }
-  return { hits, next: { expand: hits.map((hit) => hit.id) } };
+  return {
+    type: "lookup",
+    hits,
+    next: {
+      details: hits.map((hit) => hit.id),
+      traceFrom: hits.map((hit) => hit.id),
+    },
+  };
 }
 
 /** Score one node against the query; 0 means no match. */
@@ -68,6 +91,9 @@ function scoreNode(
   node: ITtscGraphNode,
   queryLc: string,
   terms: string[],
+  codeTerms: string[],
+  requestedKinds: Set<string>,
+  wantsInternal: boolean,
 ): number {
   const name = node.name.toLowerCase();
   const qualified = (node.qualifiedName ?? node.name).toLowerCase();
@@ -84,6 +110,18 @@ function scoreNode(
     score += 60;
   }
 
+  for (const codeTerm of codeTerms) {
+    if (name === codeTerm || qualified === codeTerm) {
+      score += 110;
+    } else if (qualified.endsWith(`.${codeTerm}`)) {
+      score += 95;
+    } else if (codeTerm.includes(".") && qualified.endsWith(codeTerm)) {
+      score += 85;
+    }
+  }
+
+  if (requestedKinds.has(node.kind)) score += 16;
+
   let covered = 0;
   for (const term of terms) {
     if (nameSubs.includes(term)) {
@@ -113,9 +151,68 @@ function scoreNode(
   if (node.external) score *= 0.5;
   if (node.ignored) score *= 0.3;
   if (isTestFile(node.file)) score *= 0.7;
+  if (!wantsInternal && isInternalish(node)) score *= 0.82;
   return score;
 }
 
+function wantsInternalSymbol(queryLc: string, codeTerms: string[]): boolean {
+  return (
+    /\b(internal|private|implementation|impl)\b/.test(queryLc) ||
+    codeTerms.some((term) => term.startsWith("_") || term.includes("internal"))
+  );
+}
+
+function isInternalish(node: ITtscGraphNode): boolean {
+  const name = node.qualifiedName ?? node.name;
+  return (
+    name.startsWith("_") ||
+    name.includes("._") ||
+    subwords(name).some((word) => word === "internal" || word === "internals")
+  );
+}
+
+function exactCodeTerms(query: string): string[] {
+  const out = new Set<string>();
+  for (const match of query.matchAll(/`([^`]+)`/g)) {
+    const normalized = normalizeCodeTerm(match[1] ?? "");
+    if (normalized !== undefined) out.add(normalized);
+  }
+  for (const match of query.matchAll(
+    /\b([A-Za-z_$][\w$]*)\s+(method|function|class|interface|type|variable)\b/gi,
+  )) {
+    const normalized = normalizeCodeTerm(match[1] ?? "");
+    if (normalized !== undefined) out.add(normalized);
+  }
+  for (const match of query.matchAll(
+    /\b[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+\b/g,
+  )) {
+    const normalized = normalizeCodeTerm(match[0]);
+    if (normalized !== undefined) out.add(normalized);
+  }
+  return [...out];
+}
+
+function requestedSymbolKinds(query: string): Set<string> {
+  const kinds = new Set<string>();
+  const lc = query.toLowerCase();
+  if (/\bmethods?\b/.test(lc)) kinds.add("method");
+  if (/\bfunctions?\b/.test(lc)) {
+    kinds.add("function");
+    kinds.add("method");
+    kinds.add("variable");
+  }
+  if (/\bclasses?\b/.test(lc)) kinds.add("class");
+  if (/\binterfaces?\b/.test(lc)) kinds.add("interface");
+  if (/\btypes?\b/.test(lc)) kinds.add("type");
+  if (/\bvariables?\b|\bconst\b|\blet\b/.test(lc)) kinds.add("variable");
+  return kinds;
+}
+
+function normalizeCodeTerm(raw: string): string | undefined {
+  const value = raw.trim().toLowerCase();
+  return /^[a-z_$][\w$]*(?:\.[a-z_$][\w$]*)*$/.test(value) ? value : undefined;
+}
+
 /** Non-structural in+out degree (code dependency, not nesting). */
 function degree(graph: TtscGraphMemory, id: string): number {
   let n = 0;
@@ -135,6 +232,16 @@ function isTestFile(file: string): boolean {
   );
 }
 
+function bound(
+  value: number | undefined,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const n = value === undefined || !Number.isFinite(value) ? fallback : value;
+  return Math.max(min, Math.min(max, Math.floor(n)));
+}
+
 /**
  * Split an identifier or phrase into lowercase subword tokens: CamelCase,
  * snake, dotted, and space boundaries all break, so `getHTTPResponse`,

package/src/server/runOverview.ts

@@ -1,4 +1,5 @@
 import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { ITtscGraphNode } from "../structures/ITtscGraphNode";
 import { ITtscGraphOverview } from "../structures/ITtscGraphOverview";
 
 /** Edges that express nesting/packaging, not code dependency. */
@@ -13,10 +14,10 @@ const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
  */
 export function runOverview(
   graph: TtscGraphMemory,
-  props: ITtscGraphOverview.IProps,
+  props: ITtscGraphOverview.IRequest,
 ): ITtscGraphOverview {
   const aspect = props.aspect ?? "all";
-  const want = (a: ITtscGraphOverview.IProps["aspect"]): boolean =>
+  const want = (a: ITtscGraphOverview.IRequest["aspect"]): boolean =>
     aspect === "all" || aspect === a;
 
   const byKind: Record<string, number> = {};
@@ -27,6 +28,7 @@ export function runOverview(
   }
 
   const result: ITtscGraphOverview = {
+    type: "overview",
     project: graph.project,
     counts: {
       files,
@@ -62,12 +64,12 @@ function layers(graph: TtscGraphMemory): ITtscGraphOverview.ILayer[] {
       exported: entry.exported,
     }))
     .sort((a, b) => b.files - a.files)
-    .slice(0, 16);
+    .slice(0, 10);
 }
 
 /**
  * The symbols at the center of the dependency graph, ranked by real fan-in and
- * fan-out — structural `contains`/`exports`/`imports` edges are excluded so the
+ * fan-out. Structural `contains`/`exports`/`imports` edges are excluded so the
  * ranking reflects code dependency, not nesting.
  */
 function hotspots(graph: TtscGraphMemory): ITtscGraphOverview.IHotspot[] {
@@ -80,16 +82,13 @@ function hotspots(graph: TtscGraphMemory): ITtscGraphOverview.IHotspot[] {
   return graph.nodes
     .filter((node) => !node.external && node.kind !== "file")
     .map((node) => ({
-      id: node.id,
-      name: node.qualifiedName ?? node.name,
-      kind: node.kind,
-      file: node.file,
+      ...nodeOf(node),
       fanIn: real(node.id, "in"),
       fanOut: real(node.id, "out"),
     }))
     .filter((h) => h.fanIn + h.fanOut > 0)
     .sort((a, b) => b.fanIn + b.fanOut - (a.fanIn + a.fanOut))
-    .slice(0, 15);
+    .slice(0, 10);
 }
 
 /** Declaration kinds that make up a meaningful public API surface. */
@@ -102,12 +101,13 @@ const API_KINDS = new Set<string>([
 ]);
 
 /**
- * The exported API surface: the exported symbols a consumer of the project would
- * use, ranked by how depended-on each is (real fan-in/out, structural edges
- * excluded). Ranking by dependency rather than by which file declares the most
- * exports surfaces the load-bearing types (a DataSource, a SelectQueryBuilder)
- * instead of whichever file bundles the most type aliases; test, typings, and
- * generated files are dropped so they cannot crowd the real surface out.
+ * The exported API surface: the exported symbols a consumer of the project
+ * would use, ranked by how depended-on each is (real fan-in/out, structural
+ * edges excluded). Ranking by dependency rather than by which file declares the
+ * most exports surfaces the load-bearing types (a DataSource, a
+ * SelectQueryBuilder) instead of whichever file bundles the most type aliases;
+ * test, typings, and generated files are dropped so they cannot crowd the real
+ * surface out.
  */
 function publicApi(graph: TtscGraphMemory): ITtscGraphOverview.IPublicApi[] {
   const degree = (id: string): number => {
@@ -122,21 +122,19 @@ function publicApi(graph: TtscGraphMemory): ITtscGraphOverview.IPublicApi[] {
     .exported()
     .filter((node) => API_KINDS.has(node.kind) && !isNoiseFile(node.file))
     .map((node) => ({
-      name: node.qualifiedName ?? node.name,
-      kind: node.kind,
-      file: node.file,
+      node: nodeOf(node),
       degree: degree(node.id),
     }))
     .sort((a, b) => b.degree - a.degree)
-    .slice(0, 30)
-    .map(({ name, kind, file }) => ({ name, kind, file }));
+    .slice(0, 15)
+    .map((ranked) => ranked.node);
 }
 
 /**
  * A file whose exports are noise for an architecture overview: a test, a
- * dependency's bundled `.d.ts`/typings, or generated output. The conventions are
- * universal (a `test`/`spec` path, a `typings` file), so excluding them is not
- * framework-specific — it keeps the API surface to authored, used code.
+ * dependency's bundled `.d.ts`/typings, or generated output. The conventions
+ * are universal (a `test`/`spec` path, a `typings` file), so excluding them is
+ * not framework-specific; it keeps the API surface to authored, used code.
  */
 function isNoiseFile(file: string): boolean {
   return (
@@ -152,3 +150,17 @@ function dirname(file: string): string {
   const slash = file.lastIndexOf("/");
   return slash >= 0 ? file.slice(0, slash) : ".";
 }
+
+/** Stable symbol coordinate shared by overview facets. */
+function nodeOf(node: ITtscGraphNode): ITtscGraphOverview.INode {
+  const out: ITtscGraphOverview.INode = {
+    id: node.id,
+    name: node.qualifiedName ?? node.name,
+    kind: node.kind,
+    file: node.file,
+  };
+  if (node.evidence?.startLine !== undefined) {
+    out.line = node.evidence.startLine;
+  }
+  return out;
+}