@ttsc/graph 0.16.5 → 0.16.7

package/lib/server/runQuery.js

@@ -1,147 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.runQuery = runQuery;
-const runExpand_1 = require("./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.
- */
-function runQuery(graph, props) {
-    const terms = subwords(props.query);
-    const queryLc = props.query.trim().toLowerCase();
-    if (terms.length === 0)
-        return { hits: [], next: { expand: [] } };
-    const scored = [];
-    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();
-    const hits = [];
-    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 = (0, runExpand_1.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, node, queryLc, terms) {
-    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, id) {
-    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) {
-    return kind === "contains" || kind === "exports" || kind === "imports";
-}
-function isTestFile(file) {
-    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) {
-    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());
-}
-//# sourceMappingURL=runQuery.js.map

package/lib/server/runQuery.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"runQuery.js","sourceRoot":"","sources":["../../src/server/runQuery.ts"],"names":[],"mappings":"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"}

package/lib/structures/ITtscGraphExpand.js.map

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

package/lib/structures/ITtscGraphIndex.js.map

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

package/lib/structures/ITtscGraphQuery.js.map

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

package/src/server/runExpand.ts

@@ -1,186 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-import { TtscGraphMemory } from "../model/TtscGraphMemory";
-import { ITtscGraphEdge } from "../structures/ITtscGraphEdge";
-import { ITtscGraphExpand } from "../structures/ITtscGraphExpand";
-import { ITtscGraphNode } from "../structures/ITtscGraphNode";
-import { resolveGraphHandle } from "./resolveHandle";
-
-// A whole declaration body can be large, so the full source is opt-in and capped
-// when asked for; the default response carries only the declared shape.
-const MAX_SOURCE_LINES = 200;
-// A signature is the declaration head up to the body brace — a handful of lines.
-const MAX_SIGNATURE_LINES = 6;
-// Neighbor lists are a map, not a dump; keep them scannable.
-const MAX_NEIGHBORS = 40;
-// A container's outline can be long (a big class); keep it bounded.
-const MAX_MEMBERS = 80;
-// Structural relationships are navigation, not the dependency picture expand is for.
-const STRUCTURAL_KINDS = new Set<string>(["contains", "exports", "imports"]);
-// Kinds whose value is their member outline, not a source body.
-const CONTAINER_KINDS = new Set<string>([
-  "class",
-  "interface",
-  "namespace",
-  "module",
-  "enum",
-  "file",
-]);
-
-/**
- * Resolve each handle to its declared shape — its signature, and for a
- * container the outline of its members — and, only when asked, its full source
- * body. This is the graph's edge over a plain file read: it answers from the
- * resolved structure it already holds, so the agent reads compact shape, not
- * inlined code, unless it explicitly needs a body's logic.
- */
-export function runExpand(
-  graph: TtscGraphMemory,
-  props: ITtscGraphExpand.IProps,
-): ITtscGraphExpand {
-  const wantSource = props.source === true;
-  const nodes: ITtscGraphExpand.INode[] = [];
-  const unknown: string[] = [];
-  for (const handle of props.handles) {
-    const resolved = resolveGraphHandle(graph, handle);
-    if (resolved.node === undefined) {
-      unknown.push(handle);
-      continue;
-    }
-    const node = resolved.node;
-    const expanded: ITtscGraphExpand.INode = {
-      id: node.id,
-      name: node.qualifiedName ?? node.name,
-      kind: node.kind,
-      file: node.file,
-    };
-    if (node.evidence?.startLine) expanded.line = node.evidence.startLine;
-    const sig = signatureOf(graph.project, node);
-    if (sig !== undefined) expanded.signature = sig;
-    if (CONTAINER_KINDS.has(node.kind)) {
-      const list = members(graph, node);
-      if (list.length > 0) expanded.members = list;
-    }
-    if (wantSource) {
-      const source = readSource(graph.project, node);
-      if (source !== undefined) {
-        expanded.source = source.text;
-        if (source.truncated) expanded.truncated = true;
-      }
-    }
-    if (props.neighbors === true) {
-      expanded.dependsOn = refs(graph, graph.outgoing(node.id), "to");
-      expanded.dependedOnBy = refs(graph, graph.incoming(node.id), "from");
-    }
-    nodes.push(expanded);
-  }
-  return { nodes, unknown };
-}
-
-/** The members a container owns (via `contains`), each with its own signature. */
-function members(
-  graph: TtscGraphMemory,
-  node: ITtscGraphNode,
-): ITtscGraphExpand.IMember[] {
-  const out: ITtscGraphExpand.IMember[] = [];
-  for (const edge of graph.outgoing(node.id)) {
-    if (edge.kind !== "contains") continue;
-    const member = graph.node(edge.to);
-    if (member === undefined) continue;
-    const m: ITtscGraphExpand.IMember = {
-      name: member.qualifiedName ?? member.name,
-      kind: member.kind,
-    };
-    if (member.evidence?.startLine) m.line = member.evidence.startLine;
-    const sig = signatureOf(graph.project, member);
-    if (sig !== undefined) m.signature = sig;
-    out.push(m);
-    if (out.length >= MAX_MEMBERS) break;
-  }
-  return out;
-}
-
-/** Map dependency edges to references on their far endpoint, dropping structure. */
-function refs(
-  graph: TtscGraphMemory,
-  edges: readonly ITtscGraphEdge[],
-  end: "to" | "from",
-): ITtscGraphExpand.IReference[] {
-  const out: ITtscGraphExpand.IReference[] = [];
-  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;
-    out.push({
-      id: other.id,
-      name: other.qualifiedName ?? other.name,
-      kind: other.kind,
-      relation: edge.kind,
-    });
-    if (out.length >= MAX_NEIGHBORS) break;
-  }
-  return out;
-}
-
-/** Read a file's lines once, or undefined when it cannot be read. */
-function fileLines(
-  project: string,
-  node: ITtscGraphNode,
-): string[] | undefined {
-  if (node.evidence === undefined || node.file === "") return undefined;
-  try {
-    return fs
-      .readFileSync(path.join(project, node.file), "utf8")
-      .split(/\r?\n/);
-  } catch {
-    return undefined;
-  }
-}
-
-/**
- * The declaration signature: the head of the declaration up to and including
- * the line that opens its body (`{`), or the single declaration line when there
- * is no brace, capped so a wrapped signature cannot run away.
- */
-export function signatureOf(
-  project: string,
-  node: ITtscGraphNode,
-): string | undefined {
-  const lines = fileLines(project, node);
-  const evidence = node.evidence;
-  if (lines === undefined || evidence === undefined) return undefined;
-  const start = Math.max(0, evidence.startLine - 1);
-  const out: string[] = [];
-  for (
-    let i = start;
-    i < lines.length && out.length < MAX_SIGNATURE_LINES;
-    i++
-  ) {
-    const line = lines[i];
-    if (line === undefined) break;
-    out.push(line);
-    if (line.includes("{")) break;
-  }
-  const text = out.join("\n").trim();
-  return text === "" ? undefined : text;
-}
-
-/** Slice a node's full declaration source from disk, capped at MAX_SOURCE_LINES. */
-function readSource(
-  project: string,
-  node: ITtscGraphNode,
-): { text: string; truncated: boolean } | undefined {
-  const lines = fileLines(project, node);
-  const evidence = node.evidence;
-  if (lines === undefined || evidence === undefined) return undefined;
-  const start = Math.max(0, evidence.startLine - 1);
-  const end = Math.min(evidence.endLine ?? evidence.startLine, lines.length);
-  let slice = lines.slice(start, Math.max(start + 1, end));
-  let truncated = false;
-  if (slice.length > MAX_SOURCE_LINES) {
-    slice = slice.slice(0, MAX_SOURCE_LINES);
-    truncated = true;
-  }
-  return { text: slice.join("\n"), truncated };
-}

package/src/server/runQuery.ts

@@ -1,150 +0,0 @@
-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());
-}

package/src/structures/ITtscGraphExpand.ts

@@ -1,85 +0,0 @@
-/**
- * The resolved nodes the `graph_expand` tool returns for a set of handles —
- * their declared shape (signature, and a container's members), and only on
- * request their full source body.
- */
-export interface ITtscGraphExpand {
-  nodes: ITtscGraphExpand.INode[];
-
-  /** Handles that resolved to no node, or that were ambiguous. */
-  unknown: string[];
-}
-export namespace ITtscGraphExpand {
-  /** Which handles to expand, and how much of each to return. */
-  export interface IProps {
-    /**
-     * Node ids from another tool, or dotted symbol handles such as
-     * `OrderService.create`. Pass every handle you need in one call.
-     */
-    handles: string[];
-
-    /**
-     * Also list each node's direct dependencies and dependents (the symbols it
-     * uses and the symbols that use it).
-     *
-     * @default false
-     */
-    neighbors?: boolean;
-
-    /**
-     * Return the full declaration source body too. Off by default: expand
-     * returns the declared shape — a symbol's signature, and a class/interface/
-     * namespace's member outline — which is what you usually need and a
-     * fraction of the tokens. Turn this on only for the few leaf functions or
-     * methods whose actual control-flow logic you must read.
-     *
-     * @default false
-     */
-    source?: boolean;
-  }
-
-  /** One expanded node: its declared shape, and on request its source. */
-  export interface INode {
-    id: string;
-    name: string;
-    kind: string;
-    file: string;
-    /** 1-based declaration line, when known. */
-    line?: number;
-    /** The declaration signature — its first line(s) up to the body. */
-    signature?: string;
-    /**
-     * For a class, interface, namespace, module, enum, or file: the symbols it
-     * contains, each with its own signature — the member outline a consumer
-     * reaches for, without the bodies.
-     */
-    members?: IMember[];
-    /** The full declaration source — only when `source` was requested. */
-    source?: string;
-    /** True when `source` was cut at the line cap. */
-    truncated?: boolean;
-    /** Symbols this node uses (outgoing dependency edges). */
-    dependsOn?: IReference[];
-    /** Symbols that use this node (incoming dependency edges). */
-    dependedOnBy?: IReference[];
-  }
-
-  /** One member of a container node, with its signature but not its body. */
-  export interface IMember {
-    name: string;
-    kind: string;
-    /** 1-based declaration line, when known. */
-    line?: number;
-    /** The member's declaration signature. */
-    signature?: string;
-  }
-
-  /** A dependency neighbor of an expanded node and the edge that links them. */
-  export interface IReference {
-    id: string;
-    name: string;
-    kind: string;
-    /** The edge kind connecting the two (`calls`, `type_ref`, …). */
-    relation: string;
-  }
-}

package/src/structures/ITtscGraphIndex.ts

@@ -1,100 +0,0 @@
-/** The compact source-free index returned by `graph_index` for a code question. */
-export interface ITtscGraphIndex {
-  /** The original query the index was built for. */
-  query: string;
-
-  /** Ranked symbols relevant to the query. */
-  hits: ITtscGraphIndex.IHit[];
-
-  /** Code handles written directly in the query, resolved when possible. */
-  mentions: ITtscGraphIndex.IMention[];
-
-  /** Direct dependency context for the resolved mentions and highest hits. */
-  neighborhood: ITtscGraphIndex.INeighborhood[];
-
-  /** Follow-up handles for deeper graph calls. */
-  next: ITtscGraphIndex.INext;
-
-  /** True when result caps hid additional seeds or references. */
-  truncated?: boolean;
-}
-
-export namespace ITtscGraphIndex {
-  /**
-   * Ask the graph for the first index an agent should read before opening
-   * source: ranked symbols, exact mentioned handles, and nearby dependency
-   * edges.
-   */
-  export interface IProps {
-    /**
-     * A natural code question or search phrase. Mix prose with code handles,
-     * for example `how Repository.find loads relations` or
-     * `SelectQueryBuilder.setFindOptions join aliases`.
-     */
-    query: string;
-
-    /**
-     * Maximum ranked hits to return.
-     *
-     * @default 8
-     */
-    limit?: number;
-
-    /**
-     * Maximum direct dependencies and dependents to return per indexed symbol.
-     *
-     * @default 4
-     */
-    neighbors?: number;
-  }
-
-  /** A compact symbol coordinate, optionally with its declaration signature. */
-  export interface INode {
-    id: string;
-    name: string;
-    kind: string;
-    file: string;
-    /** 1-based declaration line, when known. */
-    line?: number;
-    /** Declaration head, included only for indexed symbols. */
-    signature?: string;
-  }
-
-  /** One ranked search hit. */
-  export interface IHit extends INode {
-    /** Relative relevance; higher is a better match. */
-    score: number;
-  }
-
-  /** A code handle written in the query, with its resolution status. */
-  export interface IMention {
-    handle: string;
-    node?: INode;
-    candidates?: INode[];
-  }
-
-  /** Direct dependency context around one indexed symbol. */
-  export interface INeighborhood extends INode {
-    dependsOn: IReference[];
-    dependedOnBy: IReference[];
-  }
-
-  /** One neighboring symbol and the relationship leading to it. */
-  export interface IReference {
-    id: string;
-    name: string;
-    kind: string;
-    file: string;
-    /** 1-based declaration line, when known. */
-    line?: number;
-    relation: string;
-  }
-
-  /** Tool-call handles suggested by this first index. */
-  export interface INext {
-    /** Pass these ids to `graph_expand`, with `source: true` only when needed. */
-    expand: string[];
-    /** Pass these ids to `graph_trace` when following dependency flow. */
-    traceFrom: string[];
-  }
-}