@treeseed/sdk 0.1.1 → 0.3.0

package/dist/graph/query.js

@@ -0,0 +1,447 @@
+import path from "node:path";
+import { parseGraphDsl } from "./dsl.js";
+import { DEFAULT_GRAPH_RANKING_PROVIDER } from "./ranking.js";
+import { normalizeText } from "./schema.js";
+const RELATION_TO_EDGE_TYPE = {
+  related: "RELATES_TO",
+  depends_on: "DEPENDS_ON",
+  implements: "IMPLEMENTS",
+  references: "REFERENCES",
+  parent: "PARENT_SECTION",
+  child: "CHILD_SECTION",
+  supersedes: "SUPERSEDES"
+};
+function matchesNodeOptions(node, options) {
+  if (!node) {
+    return false;
+  }
+  if (options?.models?.length && (!node.sourceModel || !options.models.includes(node.sourceModel))) {
+    return false;
+  }
+  if (options?.nodeTypes?.length && !options.nodeTypes.includes(node.nodeType)) {
+    return false;
+  }
+  return true;
+}
+function dedupeResults(results) {
+  return [...new Map(results.map((result) => [result.node.id, result])).values()];
+}
+function tokenEstimate(text) {
+  return Math.max(1, Math.ceil(text.trim().length / 4));
+}
+function normalizeScopePath(value) {
+  return value.replace(/\\/gu, "/").replace(/\/+/gu, "/").replace(/\/$/u, "") || "/";
+}
+function stripExt(value) {
+  return value.replace(/\.(md|mdx)$/iu, "");
+}
+function nodeContentPath(node) {
+  const relativePath = typeof node.data?.relativePath === "string" ? node.data.relativePath.replace(/\.(md|mdx)$/iu, "") : typeof node.slug === "string" ? node.slug.replace(/#.*$/u, "") : "";
+  const modelPrefix = node.sourceModel ? `/${node.sourceModel}` : "";
+  if (!relativePath && modelPrefix) {
+    return modelPrefix;
+  }
+  return normalizeScopePath(`${modelPrefix}/${relativePath}`);
+}
+function nodeMatchesScope(node, scopePaths) {
+  if (!scopePaths?.length) {
+    return true;
+  }
+  const contentPath = nodeContentPath(node);
+  return scopePaths.some((scopePath) => contentPath === normalizeScopePath(scopePath) || contentPath.startsWith(`${normalizeScopePath(scopePath)}/`));
+}
+function nodeMetadataType(node) {
+  const frontmatter = node.data?.frontmatter;
+  const frontmatterType = typeof frontmatter?.type === "string" ? frontmatter.type : null;
+  return normalizeText(frontmatterType ?? node.entityType ?? node.sourceModel ?? node.nodeType);
+}
+function nodeMatchesWhere(node, filters) {
+  if (!filters?.length) {
+    return true;
+  }
+  return filters.every((filter) => {
+    const values = filter.field === "type" ? [nodeMetadataType(node)] : filter.field === "status" ? [normalizeText(node.status ?? "")] : filter.field === "audience" ? (node.audience ?? []).map(normalizeText) : filter.field === "tag" ? (node.tags ?? []).map(normalizeText) : filter.field === "domain" ? [normalizeText(node.domain ?? "")] : [];
+    const expected = Array.isArray(filter.value) ? filter.value.map(normalizeText) : [normalizeText(filter.value)];
+    return filter.op === "eq" ? expected.some((entry) => values.includes(entry)) : expected.every((entry) => values.includes(entry));
+  });
+}
+function excerptForView(node, view) {
+  const text = node.text ?? "";
+  switch (view) {
+    case "list":
+      return "";
+    case "map":
+      return `${node.title ?? node.id}`;
+    case "brief":
+      return text.slice(0, 480).trim();
+    case "full":
+    default:
+      return text;
+  }
+}
+class GraphQueryEngine {
+  constructor(state, onQuery, rankingProvider = DEFAULT_GRAPH_RANKING_PROVIDER) {
+    this.state = state;
+    this.onQuery = onQuery;
+    this.rankingProvider = rankingProvider;
+    for (const node of state.nodes) {
+      this.nodesById.set(node.id, node);
+      if (node.nodeType === "Section" && node.fileId) {
+        const current = this.fileSections.get(node.fileId) ?? [];
+        current.push(node);
+        this.fileSections.set(node.fileId, current);
+      }
+    }
+    for (const edge of state.edges) {
+      this.edgesById.set(edge.id, edge);
+      const outgoing = this.outgoing.get(edge.sourceId) ?? [];
+      outgoing.push(edge);
+      this.outgoing.set(edge.sourceId, outgoing);
+      const incoming = this.incoming.get(edge.targetId) ?? [];
+      incoming.push(edge);
+      this.incoming.set(edge.targetId, incoming);
+    }
+    for (const sections of this.fileSections.values()) {
+      sections.sort((left, right) => Number(left.data?.startOffset ?? 0) - Number(right.data?.startOffset ?? 0));
+    }
+    this.rankingIndex = this.rankingProvider.buildIndex({
+      nodes: state.nodes,
+      edges: state.edges
+    });
+  }
+  state;
+  onQuery;
+  nodesById = /* @__PURE__ */ new Map();
+  edgesById = /* @__PURE__ */ new Map();
+  outgoing = /* @__PURE__ */ new Map();
+  incoming = /* @__PURE__ */ new Map();
+  fileSections = /* @__PURE__ */ new Map();
+  rankingProvider;
+  rankingIndex;
+  filterSearchResults(results, options) {
+    return dedupeResults(
+      results.filter((result) => matchesNodeOptions(result.node, options)).slice(0, options?.limit ?? 20)
+    );
+  }
+  eligibleNodeIds(request) {
+    return statefulIds(
+      this.nodesById.values(),
+      (node) => matchesNodeOptions(node, request.options) && nodeMatchesScope(node, request.scopePaths) && nodeMatchesWhere(node, request.where)
+    );
+  }
+  searchFiles(query, options) {
+    this.onQuery?.("searchFiles", query);
+    return this.filterSearchResults(this.rankingIndex.search({ query, scope: "files", options }), options);
+  }
+  searchSections(query, options) {
+    this.onQuery?.("searchSections", query);
+    return this.filterSearchResults(this.rankingIndex.search({ query, scope: "sections", options }), options);
+  }
+  searchEntities(query, options) {
+    this.onQuery?.("searchEntities", query);
+    return this.filterSearchResults(this.rankingIndex.search({ query, scope: "entities", options }), options);
+  }
+  getNode(id) {
+    this.onQuery?.("getNode", id);
+    return this.nodesById.get(id) ?? null;
+  }
+  getNeighbors(id, options) {
+    this.onQuery?.("getNeighbors", id);
+    const edges = [
+      ...options?.direction !== "incoming" ? this.outgoing.get(id) ?? [] : [],
+      ...options?.direction !== "outgoing" ? this.incoming.get(id) ?? [] : []
+    ].filter((edge) => !options?.edgeTypes?.length || options.edgeTypes.includes(edge.type));
+    const nodes = dedupeResults(
+      edges.map((edge) => this.nodesById.get(edge.sourceId === id ? edge.targetId : edge.sourceId)).filter((node) => matchesNodeOptions(node, options)).map((node) => ({ node, score: 1, reason: "neighbor" }))
+    ).map((result) => result.node);
+    return {
+      node: this.nodesById.get(id) ?? null,
+      nodes: nodes.slice(0, options?.limit ?? nodes.length),
+      edges: edges.slice(0, options?.limit ?? edges.length)
+    };
+  }
+  followReferences(seedId, options) {
+    this.onQuery?.("followReferences", seedId);
+    const maxDepth = options?.depth ?? 2;
+    const visited = /* @__PURE__ */ new Set([seedId]);
+    const queue = [{ id: seedId, depth: 0 }];
+    const nodes = [];
+    const edges = [];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      const node = this.nodesById.get(current.id);
+      if (node && matchesNodeOptions(node, options)) {
+        nodes.push(node);
+      }
+      if (current.depth >= maxDepth) {
+        continue;
+      }
+      for (const edge of this.outgoing.get(current.id) ?? []) {
+        if (options?.edgeTypes?.length && !options.edgeTypes.includes(edge.type)) {
+          continue;
+        }
+        edges.push(edge);
+        const target = edge.targetId;
+        if (!visited.has(target) && matchesNodeOptions(this.nodesById.get(target), options)) {
+          visited.add(target);
+          queue.push({ id: target, depth: current.depth + 1 });
+        }
+      }
+    }
+    return {
+      seedId,
+      nodes: dedupeResults(nodes.map((node) => ({ node, score: 1, reason: "traversal" }))).map((result) => result.node).slice(0, options?.limit ?? nodes.length),
+      edges: [...new Map(edges.map((edge) => [edge.id, edge])).values()].slice(0, options?.limit ?? edges.length)
+    };
+  }
+  getBacklinks(id, options) {
+    this.onQuery?.("getBacklinks", id);
+    const edges = (this.incoming.get(id) ?? []).filter((edge) => !options?.edgeTypes?.length || options.edgeTypes.includes(edge.type));
+    const nodes = edges.map((edge) => this.nodesById.get(edge.sourceId)).filter((node) => matchesNodeOptions(node, options));
+    return {
+      node: this.nodesById.get(id) ?? null,
+      nodes: nodes.slice(0, options?.limit ?? nodes.length),
+      edges: edges.slice(0, options?.limit ?? edges.length)
+    };
+  }
+  getRelated(id, options) {
+    this.onQuery?.("getRelated", id);
+    const result = this.queryGraph({
+      seedIds: [id],
+      options: {
+        ...options,
+        depth: options?.depth ?? 1,
+        limit: options?.limit ?? 20,
+        maxNodes: options?.maxNodes ?? options?.limit ?? 20
+      },
+      relations: ["related", "references", "depends_on"]
+    });
+    return result.nodes.filter((entry) => entry.node.id !== id);
+  }
+  getSubgraph(seedIds, options) {
+    this.onQuery?.("getSubgraph", seedIds.join(","));
+    const aggregatedNodes = /* @__PURE__ */ new Map();
+    const aggregatedEdges = /* @__PURE__ */ new Map();
+    for (const seedId of seedIds) {
+      const traversal = this.followReferences(seedId, options);
+      for (const node of traversal.nodes) aggregatedNodes.set(node.id, node);
+      for (const edge of traversal.edges) aggregatedEdges.set(edge.id, edge);
+    }
+    return {
+      seedId: seedIds.join(","),
+      nodes: [...aggregatedNodes.values()],
+      edges: [...aggregatedEdges.values()]
+    };
+  }
+  resolveSeeds(request) {
+    this.onQuery?.("resolveSeeds", request.query ?? request.seedIds?.join(",") ?? "");
+    const explicitSeeds = request.seeds ?? [];
+    const idSeeds = (request.seedIds ?? []).map((id, index) => ({ id: `seed-id:${index}`, kind: "id", value: id }));
+    const querySeeds = request.query ? [{ id: "seed-query:0", kind: "query", value: request.query, scope: request.scope }] : [];
+    const seeds = [...explicitSeeds, ...idSeeds, ...querySeeds];
+    const matches = [];
+    const resolvedNodeIds = /* @__PURE__ */ new Set();
+    for (const seed of seeds) {
+      if (seed.kind === "id") {
+        const node = this.getNode(seed.value);
+        if (node && nodeMatchesScope(node, request.scopePaths) && nodeMatchesWhere(node, request.where)) {
+          matches.push({ node, score: 100, reason: "seed-id" });
+          resolvedNodeIds.add(node.id);
+        }
+        continue;
+      }
+      if (seed.kind === "path") {
+        const node = this.resolveReference(seed.value) ?? [...this.nodesById.values()].find((entry) => nodeContentPath(entry) === normalizeScopePath(seed.value)) ?? null;
+        if (node && nodeMatchesScope(node, request.scopePaths) && nodeMatchesWhere(node, request.where)) {
+          matches.push({ node, score: 90, reason: "seed-path" });
+          resolvedNodeIds.add(node.id);
+        }
+        continue;
+      }
+      if (seed.kind === "tag") {
+        for (const node of this.nodesById.values()) {
+          if ((node.tags ?? []).map(normalizeText).includes(normalizeText(seed.value)) && nodeMatchesScope(node, request.scopePaths) && nodeMatchesWhere(node, request.where)) {
+            matches.push({ node, score: 85, reason: "seed-tag" });
+            resolvedNodeIds.add(node.id);
+          }
+        }
+        continue;
+      }
+      if (seed.kind === "type") {
+        for (const node of this.nodesById.values()) {
+          if (nodeMetadataType(node) === normalizeText(seed.value) && nodeMatchesScope(node, request.scopePaths) && nodeMatchesWhere(node, request.where)) {
+            matches.push({ node, score: 85, reason: "seed-type" });
+            resolvedNodeIds.add(node.id);
+          }
+        }
+        continue;
+      }
+      const scoped = seed.scope === "files" ? this.searchFiles(seed.value, request.options) : seed.scope === "entities" ? this.searchEntities(seed.value, request.options) : seed.scope === "sections" ? this.searchSections(seed.value, request.options) : this.filterSearchResults(this.rankingIndex.search({ query: seed.value, scope: "all", options: request.options, request }), request.options);
+      for (const match of scoped.filter((entry) => nodeMatchesScope(entry.node, request.scopePaths) && nodeMatchesWhere(entry.node, request.where)).slice(0, request.options?.limit ?? 10)) {
+        matches.push({ ...match, reason: `${match.reason}:seed-query` });
+        resolvedNodeIds.add(match.node.id);
+      }
+    }
+    return { seeds, matches: dedupeResults(matches), resolvedNodeIds: [...resolvedNodeIds] };
+  }
+  queryGraph(request) {
+    this.onQuery?.("queryGraph", request.query ?? request.seedIds?.join(",") ?? "");
+    const resolved = this.resolveSeeds(request);
+    const allowedEdgeTypes = request.relations?.length ? request.relations.map((relation) => RELATION_TO_EDGE_TYPE[relation]) : request.options?.edgeTypes;
+    const eligibleNodeIds = this.eligibleNodeIds(request);
+    for (const seedId of resolved.resolvedNodeIds) {
+      eligibleNodeIds.add(seedId);
+    }
+    const ranked = this.rankingIndex.rankQuery({
+      request,
+      seedIds: resolved.resolvedNodeIds.filter((id) => eligibleNodeIds.has(id)),
+      seedMatches: resolved.matches.filter((match) => eligibleNodeIds.has(match.node.id)),
+      allowedNodeIds: [...eligibleNodeIds],
+      allowedEdgeTypes
+    });
+    const nodes = ranked.nodes.map((entry) => ({
+      node: this.nodesById.get(entry.nodeId),
+      score: entry.score,
+      depth: entry.depth,
+      reasons: entry.reasons,
+      diagnostics: entry.diagnostics
+    })).filter((entry) => Boolean(entry.node) && nodeMatchesScope(entry.node, request.scopePaths) && nodeMatchesWhere(entry.node, request.where));
+    const includedNodeIds = new Set(nodes.map((entry) => entry.node.id));
+    const edges = ranked.edgeIds.map((id) => this.edgesById.get(id)).filter((edge) => Boolean(edge)).filter((edge) => includedNodeIds.has(edge.sourceId) || includedNodeIds.has(edge.targetId));
+    return {
+      seedIds: resolved.resolvedNodeIds,
+      nodes,
+      edges,
+      providerId: ranked.providerId,
+      diagnostics: ranked.diagnostics
+    };
+  }
+  buildContextPack(request) {
+    this.onQuery?.("buildContextPack", request.query ?? request.seedIds?.join(",") ?? "");
+    const graphResult = this.queryGraph(request);
+    const maxTokens = request.budget?.maxTokens ?? 1800;
+    const includeMode = request.budget?.includeMode ?? (request.view === "list" || request.view === "map" ? "mixed" : request.view === "full" ? "mixed" : "mixed");
+    const view = request.view ?? "brief";
+    const includedNodeIds = /* @__PURE__ */ new Set();
+    const nodes = [];
+    let totalTokenEstimate = 0;
+    for (const entry of graphResult.nodes) {
+      if (includeMode === "files" && entry.node.nodeType !== "File") continue;
+      if (includeMode === "sections" && entry.node.nodeType !== "Section") continue;
+      if (includeMode === "mixed" && !["File", "Section"].includes(entry.node.nodeType)) continue;
+      if (includeMode === "mixed" && entry.node.nodeType === "File" && entry.node.fileId && includedNodeIds.has(entry.node.fileId)) continue;
+      const text = excerptForView(entry.node, view);
+      if (!text.trim() && !["list", "map"].includes(view)) continue;
+      const estimate = tokenEstimate(text);
+      if (totalTokenEstimate + estimate > maxTokens && nodes.length > 0) continue;
+      totalTokenEstimate += estimate;
+      includedNodeIds.add(entry.node.id);
+      nodes.push({
+        node: entry.node,
+        score: entry.score,
+        depth: entry.depth,
+        text,
+        tokenEstimate: estimate,
+        reasons: entry.reasons,
+        provenance: {
+          seedIds: graphResult.seedIds,
+          viaEdgeTypes: graphResult.edges.filter((edge) => edge.sourceId === entry.node.id || edge.targetId === entry.node.id).map((edge) => edge.type)
+        }
+      });
+    }
+    return {
+      seedIds: graphResult.seedIds,
+      totalTokenEstimate,
+      includedNodeIds: [...includedNodeIds],
+      nodes,
+      edges: graphResult.edges
+    };
+  }
+  parseDsl(source) {
+    return parseGraphDsl(source);
+  }
+  explainReferenceChain(fromId, toId) {
+    this.onQuery?.("explainReferenceChain", `${fromId}:${toId}`);
+    const queue = [{ id: fromId, path: [fromId], edges: [] }];
+    const visited = /* @__PURE__ */ new Set([fromId]);
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (current.id === toId) {
+        return {
+          fromId,
+          toId,
+          nodes: current.path.map((id) => this.nodesById.get(id)).filter((node) => Boolean(node)),
+          edges: current.edges.map((id) => this.edgesById.get(id)).filter((edge) => Boolean(edge))
+        };
+      }
+      for (const edge of this.outgoing.get(current.id) ?? []) {
+        if (visited.has(edge.targetId)) continue;
+        visited.add(edge.targetId);
+        queue.push({
+          id: edge.targetId,
+          path: [...current.path, edge.targetId],
+          edges: [...current.edges, edge.id]
+        });
+      }
+    }
+    return null;
+  }
+  resolveReference(reference, options) {
+    this.onQuery?.("resolveReference", reference);
+    const trimmed = reference.trim();
+    const [pathPart, hashPart = ""] = trimmed.split("#");
+    const directNode = this.nodesById.get(trimmed);
+    if (directNode && matchesNodeOptions(directNode, { models: options?.models })) {
+      return directNode;
+    }
+    for (const node of this.nodesById.values()) {
+      if (options?.models?.length && (!node.sourceModel || !options.models.includes(node.sourceModel))) continue;
+      if (node.nodeType !== "File" && node.nodeType !== "Section" && node.nodeType !== "Entity" && !node.entityType) continue;
+      if (node.id === `entity:${pathPart}` || node.slug === pathPart || `${node.sourceModel}/${node.slug}` === pathPart) {
+        return node;
+      }
+      if (node.path && (stripExt(node.path) === stripExt(pathPart) || stripExt(path.relative(process.cwd(), node.path)) === stripExt(pathPart))) {
+        if (hashPart) {
+          const section = (this.fileSections.get(node.id) ?? []).find((entry) => entry.headingPath === hashPart || entry.slug?.endsWith(`#${hashPart}`));
+          if (section) return section;
+        }
+        return node;
+      }
+    }
+    if (options?.fromNodeId) {
+      const source = this.nodesById.get(options.fromNodeId);
+      if (source?.path) {
+        const absolute = path.resolve(path.dirname(source.path), pathPart);
+        for (const node of this.nodesById.values()) {
+          if (node.nodeType !== "File" || !node.path) continue;
+          if (stripExt(node.path) === stripExt(absolute)) {
+            if (hashPart) {
+              const section = (this.fileSections.get(node.id) ?? []).find((entry) => entry.headingPath === hashPart || entry.heading === hashPart);
+              if (section) return section;
+            }
+            return node;
+          }
+        }
+      }
+    }
+    return null;
+  }
+  serializeIndexes() {
+    return {
+      providerId: this.rankingProvider.id,
+      ranking: this.rankingIndex.serialize?.() ?? null
+    };
+  }
+}
+function statefulIds(nodes, predicate) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const node of nodes) {
+    if (predicate(node)) {
+      ids.add(node.id);
+    }
+  }
+  return ids;
+}
+export {
+  GraphQueryEngine
+};

package/dist/graph/ranking.d.ts

@@ -0,0 +1,3 @@
+import type { SdkGraphRankingProvider } from '../sdk-types.ts';
+export declare function createDefaultGraphRankingProvider(): SdkGraphRankingProvider;
+export declare const DEFAULT_GRAPH_RANKING_PROVIDER: SdkGraphRankingProvider;