@ttsc/graph 0.16.4 → 0.16.5

package/src/server/runIndex.ts

@@ -0,0 +1,181 @@
+import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
+import { ITtscGraphIndex } from "../structures/ITtscGraphIndex";
+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;
+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.
+ */
+export function runIndex(
+  graph: TtscGraphMemory,
+  props: ITtscGraphIndex.IProps,
+): ITtscGraphIndex {
+  const query = props.query.trim();
+  const limit = bound(props.limit, DEFAULT_LIMIT, 1, MAX_LIMIT);
+  const neighborLimit = bound(
+    props.neighbors,
+    DEFAULT_NEIGHBORS,
+    0,
+    MAX_NEIGHBORS,
+  );
+
+  const queryResult = runQuery(graph, { query, limit });
+  const hits = queryResult.hits.map((hit) => ({ ...hit }));
+
+  const mentions = directMentions(query).map((handle) => {
+    const resolved = resolveGraphHandle(graph, handle, 6);
+    const mention: ITtscGraphIndex.IMention = { handle };
+    if (resolved.node !== undefined)
+      mention.node = nodeOf(graph, resolved.node);
+    if (resolved.candidates !== undefined) {
+      mention.candidates = resolved.candidates.map((node) =>
+        nodeOf(graph, node),
+      );
+    }
+    return mention;
+  });
+
+  const seeds: ITtscGraphNode[] = [];
+  const seen = new Set<string>();
+  const addSeed = (node: ITtscGraphNode | undefined): void => {
+    if (node === undefined || seen.has(node.id)) return;
+    seen.add(node.id);
+    seeds.push(node);
+  };
+  for (const mention of mentions) {
+    if (mention.node !== undefined) addSeed(graph.node(mention.node.id));
+  }
+  for (const hit of hits) addSeed(graph.node(hit.id));
+
+  let truncated = seeds.length > MAX_SEEDS;
+  const neighborhood: ITtscGraphIndex.INeighborhood[] = [];
+  for (const seed of seeds.slice(0, MAX_SEEDS)) {
+    const outgoing = refs(graph, graph.outgoing(seed.id), "to", neighborLimit);
+    const incoming = refs(
+      graph,
+      graph.incoming(seed.id),
+      "from",
+      neighborLimit,
+    );
+    if (outgoing.truncated || incoming.truncated) truncated = true;
+    neighborhood.push({
+      ...nodeOf(graph, seed),
+      dependsOn: outgoing.items,
+      dependedOnBy: incoming.items,
+    });
+  }
+
+  return {
+    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),
+    },
+    ...(truncated ? { truncated: true } : {}),
+  };
+}
+
+function nodeOf(
+  graph: TtscGraphMemory,
+  node: ITtscGraphNode,
+): ITtscGraphIndex.INode {
+  const out: ITtscGraphIndex.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;
+  const signature = signatureOf(graph.project, node);
+  if (signature !== undefined) out.signature = signature;
+  return out;
+}
+
+function refOf(
+  node: ITtscGraphNode,
+  edge: ITtscGraphEdge,
+): ITtscGraphIndex.IReference {
+  const out: ITtscGraphIndex.IReference = {
+    id: node.id,
+    name: node.qualifiedName ?? node.name,
+    kind: node.kind,
+    file: node.file,
+    relation: edge.kind,
+  };
+  if (node.evidence?.startLine !== undefined)
+    out.line = node.evidence.startLine;
+  return out;
+}
+
+function refs(
+  graph: TtscGraphMemory,
+  edges: readonly ITtscGraphEdge[],
+  end: "to" | "from",
+  limit: number,
+): { items: ITtscGraphIndex.IReference[]; truncated: boolean } {
+  const items: ITtscGraphIndex.IReference[] = [];
+  const seen = new Set<string>();
+  let available = 0;
+  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 || other.kind === "file") continue;
+    const key = `${edge.kind}:${other.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    available++;
+    if (items.length < limit) items.push(refOf(other, edge));
+  }
+  return { items, truncated: available > items.length };
+}
+
+function directMentions(query: string): string[] {
+  const handles = new Set<string>();
+  for (const match of query.matchAll(/`([^`]+)`/g)) {
+    const handle = normalizeHandle(match[1] ?? "");
+    if (handle !== undefined) handles.add(handle);
+  }
+  for (const match of query.matchAll(
+    /\b[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)+\b/g,
+  )) {
+    const handle = normalizeHandle(match[0]);
+    if (handle !== undefined) handles.add(handle);
+  }
+  return [...handles];
+}
+
+function normalizeHandle(raw: string): string | undefined {
+  const value = raw.trim();
+  return /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*$/.test(value)
+    ? value
+    : undefined;
+}
+
+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)));
+}

package/src/server/runOverview.ts

@@ -0,0 +1,154 @@
+import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { ITtscGraphOverview } from "../structures/ITtscGraphOverview";
+
+/** Edges that express nesting/packaging, not code dependency. */
+const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
+
+/**
+ * Project a compact, source-read-free architecture map: counts by kind, folder
+ * layering with export density, the highest-dependency symbols (ranked by real
+ * fan-in/out, excluding structural edges so nesting does not masquerade as
+ * dependency), and the export surface by file. Output is bounded so a model
+ * reads structure cheaply.
+ */
+export function runOverview(
+  graph: TtscGraphMemory,
+  props: ITtscGraphOverview.IProps,
+): ITtscGraphOverview {
+  const aspect = props.aspect ?? "all";
+  const want = (a: ITtscGraphOverview.IProps["aspect"]): boolean =>
+    aspect === "all" || aspect === a;
+
+  const byKind: Record<string, number> = {};
+  let files = 0;
+  for (const node of graph.nodes) {
+    byKind[node.kind] = (byKind[node.kind] ?? 0) + 1;
+    if (node.kind === "file") files++;
+  }
+
+  const result: ITtscGraphOverview = {
+    project: graph.project,
+    counts: {
+      files,
+      nodes: graph.nodes.length,
+      edges: graph.edges.length,
+      byKind,
+    },
+  };
+  if (want("layers")) result.layers = layers(graph);
+  if (want("hotspots")) result.hotspots = hotspots(graph);
+  if (want("publicApi")) result.publicApi = publicApi(graph);
+  return result;
+}
+
+/** Folder-level layering: how source and its export surface spread by directory. */
+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;
+    const dir = dirname(node.file);
+    let entry = byDir.get(dir);
+    if (!entry) {
+      entry = { files: new Set(), exported: 0 };
+      byDir.set(dir, entry);
+    }
+    entry.files.add(node.file);
+    if (node.exported) entry.exported++;
+  }
+  return [...byDir.entries()]
+    .map(([dir, entry]) => ({
+      dir,
+      files: entry.files.size,
+      exported: entry.exported,
+    }))
+    .sort((a, b) => b.files - a.files)
+    .slice(0, 16);
+}
+
+/**
+ * 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
+ * ranking reflects code dependency, not nesting.
+ */
+function hotspots(graph: TtscGraphMemory): ITtscGraphOverview.IHotspot[] {
+  const real = (id: string, side: "in" | "out"): number => {
+    const edges = side === "in" ? graph.incoming(id) : graph.outgoing(id);
+    let n = 0;
+    for (const edge of edges) if (!STRUCTURAL_KINDS.has(edge.kind)) n++;
+    return n;
+  };
+  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,
+      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);
+}
+
+/** Declaration kinds that make up a meaningful public API surface. */
+const API_KINDS = new Set<string>([
+  "class",
+  "interface",
+  "function",
+  "type",
+  "enum",
+]);
+
+/**
+ * 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 => {
+    let n = 0;
+    for (const edge of graph.outgoing(id))
+      if (!STRUCTURAL_KINDS.has(edge.kind)) n++;
+    for (const edge of graph.incoming(id))
+      if (!STRUCTURAL_KINDS.has(edge.kind)) n++;
+    return n;
+  };
+  return graph
+    .exported()
+    .filter((node) => API_KINDS.has(node.kind) && !isNoiseFile(node.file))
+    .map((node) => ({
+      name: node.qualifiedName ?? node.name,
+      kind: node.kind,
+      file: node.file,
+      degree: degree(node.id),
+    }))
+    .sort((a, b) => b.degree - a.degree)
+    .slice(0, 30)
+    .map(({ name, kind, file }) => ({ name, kind, file }));
+}
+
+/**
+ * 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.
+ */
+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)
+  );
+}
+
+/** The parent directory of a project-relative path (`.` at the root). */
+function dirname(file: string): string {
+  const slash = file.lastIndexOf("/");
+  return slash >= 0 ? file.slice(0, slash) : ".";
+}

package/src/server/runQuery.ts

@@ -0,0 +1,150 @@
+import { TtscGraphMemory } from "../model/TtscGraphMemory";
+import { ITtscGraphNode } from "../structures/ITtscGraphNode";
+import { ITtscGraphQuery } from "../structures/ITtscGraphQuery";
+import { signatureOf } from "./runExpand";
+
+// One file should not crowd out the rest of the ranking, so cap hits per file.
+const PER_FILE = 3;
+const DEFAULT_LIMIT = 12;
+
+/**
+ * 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 runQuery(
+  graph: TtscGraphMemory,
+  props: ITtscGraphQuery.IProps,
+): ITtscGraphQuery {
+  const terms = subwords(props.query);
+  const queryLc = props.query.trim().toLowerCase();
+  if (terms.length === 0) return { hits: [], next: { expand: [] } };
+
+  const scored: ITtscGraphQuery.IHit[] = [];
+  for (const node of graph.nodes) {
+    if (node.kind === "file") continue;
+    const score = scoreNode(graph, node, queryLc, terms);
+    if (score <= 0) continue;
+    scored.push({
+      id: node.id,
+      name: node.qualifiedName ?? node.name,
+      kind: node.kind,
+      file: node.file,
+      line: node.evidence?.startLine,
+      score: Math.round(score),
+    });
+  }
+
+  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 perFile = new Map<string, number>();
+  const hits: ITtscGraphQuery.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 the shortlist, so the read cost is
+  // bounded — so the model can often answer from the query alone, no expand.
+  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) } };
+}
+
+/** Score one node against the query; 0 means no match. */
+function scoreNode(
+  graph: TtscGraphMemory,
+  node: ITtscGraphNode,
+  queryLc: string,
+  terms: string[],
+): 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;
+  }
+
+  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.external) score *= 0.5;
+  if (node.ignored) score *= 0.3;
+  if (isTestFile(node.file)) score *= 0.7;
+  return score;
+}
+
+/** 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)
+  );
+}
+
+/**
+ * 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());
+}