@treeseed/sdk 0.1.2 → 0.3.1

package/dist/graph/dsl.d.ts

@@ -0,0 +1,2 @@
+import type { SdkGraphDslParseResult } from '../sdk-types.ts';
+export declare function parseGraphDsl(source: string): SdkGraphDslParseResult;

package/dist/graph/dsl.js

@@ -0,0 +1,243 @@
+const CLAUSE_KEYWORDS = /* @__PURE__ */ new Set(["for", "in", "via", "depth", "where", "limit", "budget", "as"]);
+const VALID_STAGES = ["plan", "implement", "research", "debug", "review"];
+const VALID_VIEWS = ["list", "brief", "full", "map"];
+const VALID_RELATIONS = ["related", "depends_on", "implements", "references", "parent", "child", "supersedes"];
+const VALID_WHERE_FIELDS = /* @__PURE__ */ new Set(["type", "status", "audience", "tag", "domain"]);
+function tokenize(source) {
+  const tokens = [];
+  let current = "";
+  let quote = null;
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    if (quote) {
+      if (char === quote) {
+        tokens.push(current);
+        current = "";
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      if (current.trim()) {
+        tokens.push(current.trim());
+        current = "";
+      }
+      quote = char;
+      continue;
+    }
+    if (/\s/u.test(char)) {
+      if (current.trim()) {
+        tokens.push(current.trim());
+        current = "";
+      }
+      continue;
+    }
+    current += char;
+  }
+  if (quote) {
+    return { tokens, error: "Unterminated quoted string in ctx query." };
+  }
+  if (current.trim()) {
+    tokens.push(current.trim());
+  }
+  return { tokens, error: null };
+}
+function nextClauseIndex(tokens, start) {
+  for (let index = start; index < tokens.length; index += 1) {
+    if (CLAUSE_KEYWORDS.has(tokens[index])) {
+      return index;
+    }
+  }
+  return tokens.length;
+}
+function nextClauseIndexForClause(tokens, start, clause) {
+  for (let index = start; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (!CLAUSE_KEYWORDS.has(token)) {
+      continue;
+    }
+    if (clause === "where" && token === "in") {
+      continue;
+    }
+    return index;
+  }
+  return tokens.length;
+}
+function parseTarget(rawTarget) {
+  if (rawTarget.startsWith("@")) {
+    return { id: "seed:0", kind: "id", value: rawTarget.slice(1) };
+  }
+  if (rawTarget.startsWith("/")) {
+    return { id: "seed:0", kind: "path", value: rawTarget };
+  }
+  if (rawTarget.startsWith("#")) {
+    return { id: "seed:0", kind: "tag", value: rawTarget.slice(1) };
+  }
+  if (rawTarget.startsWith("%")) {
+    return { id: "seed:0", kind: "type", value: rawTarget.slice(1) };
+  }
+  return { id: "seed:0", kind: "query", value: rawTarget };
+}
+function parseWhere(expression) {
+  const equality = expression.match(/^\s*([a-z_]+)\s*=\s*([^)]+?)\s*$/iu);
+  if (equality) {
+    const field = equality[1].toLowerCase();
+    if (!VALID_WHERE_FIELDS.has(field)) {
+      return { error: `Unsupported where field "${field}".` };
+    }
+    return [{ field, op: "eq", value: equality[2].trim() }];
+  }
+  const membership = expression.match(/^\s*([a-z_]+)\s+in\s*\(([^)]*)\)\s*$/iu);
+  if (membership) {
+    const field = membership[1].toLowerCase();
+    if (!VALID_WHERE_FIELDS.has(field)) {
+      return { error: `Unsupported where field "${field}".` };
+    }
+    const values = membership[2].split(",").map((entry) => entry.trim()).filter(Boolean);
+    if (values.length === 0) {
+      return { error: "where in (...) must include at least one value." };
+    }
+    return [{ field, op: "in", value: values }];
+  }
+  return { error: `Invalid where clause "${expression}".` };
+}
+function parseGraphDsl(source) {
+  const errors = [];
+  const request = {
+    stage: "plan",
+    relations: ["related", "references"],
+    view: "brief",
+    options: {
+      depth: 1,
+      limit: 8,
+      maxNodes: 8
+    }
+  };
+  const budget = {};
+  const seenClauses = /* @__PURE__ */ new Set();
+  const tokenized = tokenize(source.trim());
+  if (tokenized.error) {
+    return { ok: false, query: null, errors: [tokenized.error] };
+  }
+  const { tokens } = tokenized;
+  if (tokens.length === 0) {
+    return { ok: false, query: null, errors: ["ctx query is empty."] };
+  }
+  if (tokens[0] !== "ctx") {
+    return { ok: false, query: null, errors: ["ctx query must start with the `ctx` command."] };
+  }
+  const firstClause = nextClauseIndex(tokens, 1);
+  const targetTokens = tokens.slice(1, firstClause);
+  if (targetTokens.length === 0) {
+    return { ok: false, query: null, errors: ["ctx query must include a target."] };
+  }
+  request.seeds = [parseTarget(targetTokens.join(" "))];
+  for (let index = firstClause; index < tokens.length; ) {
+    const clause = tokens[index];
+    if (!CLAUSE_KEYWORDS.has(clause)) {
+      errors.push(`Unexpected token "${clause}".`);
+      index += 1;
+      continue;
+    }
+    if (seenClauses.has(clause)) {
+      errors.push(`Clause "${clause}" may only appear once.`);
+    }
+    seenClauses.add(clause);
+    const valueStart = index + 1;
+    const valueEnd = nextClauseIndexForClause(tokens, valueStart, clause);
+    const rawValue = tokens.slice(valueStart, valueEnd).join(" ").trim();
+    if (!rawValue) {
+      errors.push(`Clause "${clause}" requires a value.`);
+      index = valueEnd;
+      continue;
+    }
+    switch (clause) {
+      case "for":
+        if (!VALID_STAGES.includes(rawValue)) {
+          errors.push(`Invalid stage "${rawValue}".`);
+        } else {
+          request.stage = rawValue;
+        }
+        break;
+      case "in": {
+        const scopePaths = rawValue.split("+").map((entry) => entry.trim()).filter(Boolean);
+        if (scopePaths.length === 0 || scopePaths.some((entry) => !entry.startsWith("/"))) {
+          errors.push(`Invalid scope path list "${rawValue}".`);
+        } else {
+          request.scopePaths = scopePaths;
+        }
+        break;
+      }
+      case "via": {
+        const relations = rawValue.split(",").map((entry) => entry.trim().toLowerCase()).filter(Boolean);
+        const invalid = relations.filter((entry) => !VALID_RELATIONS.includes(entry));
+        if (invalid.length > 0) {
+          errors.push(`Invalid relations: ${invalid.join(", ")}`);
+        } else {
+          request.relations = relations;
+        }
+        break;
+      }
+      case "depth": {
+        const depth = Number(rawValue);
+        if (!Number.isInteger(depth) || depth < 0 || depth > 3) {
+          errors.push(`Depth must be an integer between 0 and 3, received "${rawValue}".`);
+        } else {
+          request.options = { ...request.options ?? {}, depth };
+        }
+        break;
+      }
+      case "where": {
+        const parsed = parseWhere(rawValue);
+        if ("error" in parsed) {
+          errors.push(parsed.error);
+        } else {
+          request.where = parsed;
+        }
+        break;
+      }
+      case "limit": {
+        const limit = Number(rawValue);
+        if (!Number.isInteger(limit) || limit <= 0) {
+          errors.push(`Limit must be a positive integer, received "${rawValue}".`);
+        } else {
+          request.options = { ...request.options ?? {}, limit, maxNodes: limit };
+          budget.maxNodes = limit;
+        }
+        break;
+      }
+      case "budget": {
+        const maxTokens = Number(rawValue);
+        if (!Number.isInteger(maxTokens) || maxTokens <= 0) {
+          errors.push(`Budget must be a positive integer, received "${rawValue}".`);
+        } else {
+          budget.maxTokens = maxTokens;
+        }
+        break;
+      }
+      case "as":
+        if (!VALID_VIEWS.includes(rawValue)) {
+          errors.push(`Invalid view "${rawValue}".`);
+        } else {
+          request.view = rawValue;
+        }
+        break;
+      default:
+        errors.push(`Unknown clause "${clause}".`);
+    }
+    index = valueEnd;
+  }
+  if (Object.keys(budget).length > 0) {
+    request.budget = budget;
+  }
+  return {
+    ok: errors.length === 0,
+    query: errors.length === 0 ? request : null,
+    errors
+  };
+}
+export {
+  parseGraphDsl
+};

package/dist/graph/query.d.ts

@@ -0,0 +1,47 @@
+import type { SdkContextPack, SdkContextPackRequest, SdkGraphEdge, SdkGraphNode, SdkGraphQueryOptions, SdkGraphQueryRequest, SdkGraphQueryResult, SdkGraphPathExplanation, SdkGraphRankingProvider, SdkGraphSearchOptions, SdkGraphSearchResult, SdkGraphSeedResolution, SdkGraphTraversalResult } from '../sdk-types.ts';
+import type { GraphBuildState } from './build.ts';
+export declare class GraphQueryEngine {
+    private readonly state;
+    private readonly onQuery?;
+    private readonly nodesById;
+    private readonly edgesById;
+    private readonly outgoing;
+    private readonly incoming;
+    private readonly fileSections;
+    private readonly rankingProvider;
+    private readonly rankingIndex;
+    constructor(state: GraphBuildState, onQuery?: ((name: string, detail?: string) => void) | undefined, rankingProvider?: SdkGraphRankingProvider);
+    private filterSearchResults;
+    private eligibleNodeIds;
+    searchFiles(query: string, options?: SdkGraphSearchOptions): SdkGraphSearchResult[];
+    searchSections(query: string, options?: SdkGraphSearchOptions): SdkGraphSearchResult[];
+    searchEntities(query: string, options?: SdkGraphSearchOptions): SdkGraphSearchResult[];
+    getNode(id: string): SdkGraphNode | null;
+    getNeighbors(id: string, options?: SdkGraphQueryOptions): {
+        node: SdkGraphNode | null;
+        nodes: SdkGraphNode[];
+        edges: SdkGraphEdge[];
+    };
+    followReferences(seedId: string, options?: SdkGraphQueryOptions): SdkGraphTraversalResult;
+    getBacklinks(id: string, options?: SdkGraphQueryOptions): {
+        node: SdkGraphNode | null;
+        nodes: SdkGraphNode[];
+        edges: SdkGraphEdge[];
+    };
+    getRelated(id: string, options?: SdkGraphQueryOptions): import("../sdk-types.ts").SdkGraphQueryNodeResult[];
+    getSubgraph(seedIds: string[], options?: SdkGraphQueryOptions): SdkGraphTraversalResult;
+    resolveSeeds(request: SdkGraphQueryRequest): SdkGraphSeedResolution;
+    queryGraph(request: SdkGraphQueryRequest): SdkGraphQueryResult;
+    buildContextPack(request: SdkContextPackRequest): SdkContextPack;
+    parseDsl(source: string): import("../sdk-types.ts").SdkGraphDslParseResult;
+    explainReferenceChain(fromId: string, toId: string): SdkGraphPathExplanation | null;
+    resolveReference(reference: string, options?: {
+        fromNodeId?: string;
+        fromPath?: string;
+        models?: string[];
+    }): SdkGraphNode | null;
+    serializeIndexes(): {
+        providerId: string;
+        ranking: Record<string, unknown> | null;
+    };
+}