@ttsc/graph 0.16.5 → 0.16.7

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

@@ -1,28 +1,29 @@
 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 { resultGuide, resultNext } from "./resultGuide";
+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 +33,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 +62,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,16 +80,19 @@ 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),
-    },
+    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 } : {}),
   };
 }
@@ -96,8 +100,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 +111,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 +129,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 +139,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 +152,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 +231,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/runLookup.ts

@@ -0,0 +1,284 @@
+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.
+const PER_FILE = 3;
+const DEFAULT_LIMIT = 5;
+const MAX_LIMIT = 6;
+
+/**
+ * Rank the graph's symbols against a natural query. Scoring blends exact and
+ * dotted-name matches, CamelCase/subword coverage, file-path terms, a prefix
+ * bonus, and dependency centrality, then dampens external, generated, and test
+ * nodes and caps per file so the result is a diverse, relevant shortlist rather
+ * than one file's roster.
+ */
+export function runLookup(
+  graph: TtscGraphMemory,
+  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();
+  const wantsInternal = wantsInternalSymbol(queryLc, codeTerms);
+  const wantsSupport = wantsSupportSymbol(queryLc);
+  const includeExternal = props.includeExternal === true;
+  if (terms.length === 0)
+    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,
+      queryLc,
+      terms,
+      codeTerms,
+      requestedKinds,
+      wantsInternal,
+      wantsSupport,
+    );
+    if (score <= 0) continue;
+    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 = 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);
+    hits.push(hit);
+    if (hits.length >= limit) break;
+  }
+
+  // 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 {
+    type: "lookup",
+    hits,
+    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.",
+    ),
+  };
+}
+
+/** Score one node against the query; 0 means no match. */
+function scoreNode(
+  graph: TtscGraphMemory,
+  node: ITtscGraphNode,
+  queryLc: string,
+  terms: string[],
+  codeTerms: string[],
+  requestedKinds: Set<string>,
+  wantsInternal: boolean,
+  wantsSupport: boolean,
+): number {
+  const name = node.name.toLowerCase();
+  const qualified = (node.qualifiedName ?? node.name).toLowerCase();
+  const nameSubs = subwords(node.name);
+  const qualifiedSubs = subwords(node.qualifiedName ?? node.name);
+  const pathSubs = subwords(node.file);
+
+  let score = 0;
+  if (queryLc === name || queryLc === qualified) {
+    score += 100;
+  } else if (qualified.includes(".") && queryLc.includes(qualified)) {
+    score += 85;
+  } else if (queryLc.includes(".") && qualified.includes(queryLc)) {
+    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)) {
+      score += 12;
+      covered++;
+    } else if (qualifiedSubs.includes(term)) {
+      score += 8;
+      covered++;
+    } else if (name.includes(term)) {
+      score += 5;
+      covered++;
+    } else if (pathSubs.includes(term)) {
+      score += 3;
+    }
+  }
+  // Every query term landed somewhere in the name: a strong whole-query match.
+  if (covered === terms.length) score += 10;
+  if (name.startsWith(terms[0]!)) score += 4;
+
+  if (score <= 0) return 0;
+
+  // Centrality: a symbol the codebase leans on is a likelier target.
+  const fan = degree(graph, node.id);
+  score += Math.min(8, Math.log2(1 + fan) * 2);
+
+  // Dampen what is rarely the intended target.
+  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) ||
+    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;
+  for (const edge of graph.outgoing(id)) if (!isStructural(edge.kind)) n++;
+  for (const edge of graph.incoming(id)) if (!isStructural(edge.kind)) n++;
+  return n;
+}
+
+function isStructural(kind: string): boolean {
+  return kind === "contains" || kind === "exports" || kind === "imports";
+}
+
+function isTestFile(file: string): boolean {
+  return (
+    /(^|\/)(test|tests|__tests__|spec)\//.test(file) ||
+    /\.(test|spec)\.[cm]?tsx?$/.test(file)
+  );
+}
+
+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`,
+ * `find_by_id`, and `OrderService.create` tokenize the way a query would.
+ */
+function subwords(text: string): string[] {
+  return text
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+    .split(/[^a-zA-Z0-9]+/)
+    .filter((w) => w.length > 0)
+    .map((w) => w.toLowerCase());
+}