@graphpilot-oss/graphpilot 0.0.1 → 1.0.0

package/src/parser.ts

@@ -1,138 +0,0 @@
-import Parser from 'tree-sitter';
-// @ts-ignore — tree-sitter-typescript ships JS, has no types
-import TS from 'tree-sitter-typescript';
-import { readFileSync, statSync } from 'node:fs';
-import { extname } from 'node:path';
-import { MAX_FILE_BYTES } from './validation.js';
-
-export interface ParsedFile {
-  path: string;
-  lang: 'typescript' | 'tsx' | 'javascript' | 'jsx';
-  tree: Parser.Tree;
-  source: string;
-}
-
-const PARSER_CACHE = new Map<string, Parser>();
-
-function getParser(lang: ParsedFile['lang']): Parser {
-  if (PARSER_CACHE.has(lang)) return PARSER_CACHE.get(lang)!;
-  const p = new Parser();
-  // Cast around the peer-dep type-version skew between tree-sitter and
-  // tree-sitter-typescript. Runtime is fine; only the .d.ts files disagree.
-  const langs = TS as { typescript: Parser.Language; tsx: Parser.Language };
-  switch (lang) {
-    case 'typescript':
-      p.setLanguage(langs.typescript);
-      break;
-    case 'tsx':
-      p.setLanguage(langs.tsx);
-      break;
-    case 'javascript':
-    case 'jsx':
-      p.setLanguage(langs.typescript);
-      break;
-  }
-  PARSER_CACHE.set(lang, p);
-  return p;
-}
-
-export function detectLang(path: string): ParsedFile['lang'] | null {
-  switch (extname(path).toLowerCase()) {
-    case '.ts':
-      return 'typescript';
-    case '.tsx':
-      return 'tsx';
-    case '.js':
-    case '.mjs':
-    case '.cjs':
-      return 'javascript';
-    case '.jsx':
-      return 'jsx';
-    default:
-      return null;
-  }
-}
-
-export function parseFile(path: string): ParsedFile | null {
-  const lang = detectLang(path);
-  if (!lang) return null;
-  // Defence against T1 (resource exhaustion): skip oversized files rather than
-  // OOM the process. 5 MB is enough for any real source file.
-  let size: number;
-  try {
-    size = statSync(path).size;
-  } catch {
-    return null;
-  }
-  if (size > MAX_FILE_BYTES) return null;
-  const source = readFileSync(path, 'utf8');
-  return parseSource(path, source, lang);
-}
-
-export function parseSource(path: string, source: string, lang: ParsedFile['lang']): ParsedFile {
-  const tree = getParser(lang).parse(source);
-  return { path, lang, tree, source };
-}
-
-/**
- * Walk the tree and yield every node. Depth-first, pre-order.
- *
- * Iterative (not recursive) so a deeply-nested AST can't blow the JS stack.
- * Tree-sitter trees on real codebases hit ~50–80 depth; pathological generated
- * code can go much deeper. Defence against T1.
- */
-export function* walk(node: Parser.SyntaxNode): Generator<Parser.SyntaxNode> {
-  const stack: Parser.SyntaxNode[] = [node];
-  while (stack.length > 0) {
-    const cur = stack.pop()!;
-    yield cur;
-    // Push children in reverse so they pop in original order (preserves
-    // pre-order traversal — matters for callers that rely on source ordering).
-    for (let i = cur.childCount - 1; i >= 0; i--) {
-      const child = cur.child(i);
-      if (child) stack.push(child);
-    }
-  }
-}
-
-/**
- * Day-2 deliverable: list every function name in a parsed file.
- * Catches: function declarations, arrow functions assigned to consts,
- * class methods, function expressions assigned to variables.
- */
-export function listFunctions(parsed: ParsedFile): string[] {
-  const names: string[] = [];
-  for (const node of walk(parsed.tree.rootNode)) {
-    const name = functionNameOf(node);
-    if (name) names.push(name);
-  }
-  return names;
-}
-
-function functionNameOf(node: Parser.SyntaxNode): string | null {
-  switch (node.type) {
-    case 'function_declaration':
-    case 'generator_function_declaration':
-    case 'method_definition':
-    case 'function_signature': {
-      const nameNode = node.childForFieldName('name');
-      return nameNode?.text ?? null;
-    }
-    case 'variable_declarator': {
-      // const foo = () => ... | const foo = function() {}
-      const valueNode = node.childForFieldName('value');
-      if (
-        valueNode &&
-        (valueNode.type === 'arrow_function' ||
-          valueNode.type === 'function_expression' ||
-          valueNode.type === 'function')
-      ) {
-        const nameNode = node.childForFieldName('name');
-        return nameNode?.text ?? null;
-      }
-      return null;
-    }
-    default:
-      return null;
-  }
-}

package/src/provenance.ts

@@ -1,115 +0,0 @@
-/**
- * Provenance / evidence anchors for tool responses.
- *
- * Why this exists: agents hallucinate. The most common Cursor / Claude
- * Code failure pattern is "the model called a function that doesn't
- * exist" — and the user has no quick way to verify a tool's claim
- * before acting on it.
- *
- * Solution: every result we return carries an evidence anchor — a
- * structured `{file, line, sha, excerpt}` reference that the agent
- * can include verbatim in its reply. The user (or the agent itself)
- * can then jump to the file/line and confirm the cited code matches
- * the claim. If we ever fabricate, the anchor exposes us instantly.
- *
- * Format design:
- *   - Path is relative to the indexed root (portable).
- *   - Line is 1-indexed (matches editor convention).
- *   - SHA is optional — null when the indexed repo isn't a git repo.
- *     When present, it's the 7-char short SHA of the index time.
- *   - Excerpt is optional and short (~200 chars) — for symbol records
- *     it's the signature line. For edges it's the call expression.
- *
- * Per the differentiation research, this is the SINGLE feature no
- * competitor in the 15+ landscape has shipped. See
- * .notes/differentiation-research-2026-05-21.md §1.3.
- */
-
-import type { SymbolRecord } from './symbols.js';
-import type { CallEdge } from './edges.js';
-
-/** A single evidence anchor pointing at a specific location in the repo. */
-export interface Provenance {
-  /** Relative path from the indexed repo root, e.g. "src/auth.ts". */
-  file: string;
-  /** 1-indexed line number. */
-  line: number;
-  /** Optional 1-indexed column. */
-  column?: number;
-  /** End line, when the entity spans multiple lines. */
-  endLine?: number;
-  /** Short git SHA (7 chars) at index time. Null if not a git repo. */
-  sha?: string | null;
-  /** Short text excerpt — symbol signature, call expression, etc. */
-  excerpt?: string;
-}
-
-const MAX_EXCERPT_LEN = 200;
-
-function clipExcerpt(s: string | undefined): string | undefined {
-  if (!s) return undefined;
-  const trimmed = s.trim();
-  if (trimmed.length === 0) return undefined;
-  return trimmed.length > MAX_EXCERPT_LEN ? trimmed.slice(0, MAX_EXCERPT_LEN - 1) + '…' : trimmed;
-}
-
-/**
- * Make provenance for a symbol. Excerpt is the symbol's stored
- * signature (already secret-redacted by T3).
- */
-export function symbolProvenance(s: SymbolRecord, sha: string | null): Provenance {
-  return {
-    file: s.file,
-    line: s.line,
-    column: s.column,
-    endLine: s.endLine,
-    sha: sha ?? null,
-    excerpt: clipExcerpt(s.signature),
-  };
-}
-
-/**
- * Make provenance for a call edge. Points at the CALL SITE (where the
- * call happens), not the callee's definition. The callee's own
- * provenance is available via `symbolProvenance(idx.findById(edge.toId))`
- * when toId is non-null.
- */
-export function edgeProvenance(e: CallEdge, sha: string | null): Provenance {
-  return {
-    file: e.file,
-    line: e.line,
-    column: e.column,
-    sha: sha ?? null,
-    // No excerpt for edges — we don't store the call line text.
-    // (Future v0.2: capture the call line at index time so the agent
-    // sees the actual call expression.)
-  };
-}
-
-/**
- * Format a Provenance as a single-line human/agent-readable string.
- * Used inline in tool text responses.
- *
- * Examples:
- *   src/auth.ts:42                    (no sha — not a git repo)
- *   src/auth.ts:42 @ ab12cd3          (with sha)
- *   src/auth.ts:42:5 @ ab12cd3        (with column)
- */
-export function formatProvenance(p: Provenance): string {
-  let out = p.file + ':' + p.line;
-  if (p.column !== undefined) out += ':' + p.column;
-  if (p.sha) out += ' @ ' + p.sha;
-  return out;
-}
-
-/**
- * Format a Provenance as a verifiable evidence tag the agent can
- * include in its reply. The agent's user (or a downstream tool) can
- * paste this directly into a search.
- *
- * Example:
- *   [evidence: src/auth.ts:42 @ ab12cd3]
- */
-export function formatEvidenceTag(p: Provenance): string {
-  return `[evidence: ${formatProvenance(p)}]`;
-}

package/src/query.ts

@@ -1,148 +0,0 @@
-import type { Graph } from './storage.js';
-import type { SymbolRecord } from './symbols.js';
-import type { CallEdge } from './edges.js';
-
-export interface RecallOptions {
-  /** Max results. Default 10. Capped at 100. */
-  limit?: number;
-  /**
-   * If true, match if the query is a substring of the symbol name.
-   * If false (default), require exact case-insensitive match.
-   */
-  substring?: boolean;
-}
-
-export interface EdgeQueryOptions {
-  /** Max edges to return. Default 50. Capped at 500. */
-  limit?: number;
-  /**
-   * If true, include edges where the callee is unresolved (toId === null).
-   * Default true — agents usually want to see those too.
-   */
-  includeUnresolved?: boolean;
-}
-
-const HARD_RESULT_CAP = 100;
-const HARD_EDGE_CAP = 500;
-
-/**
- * Pre-computed lookup tables over a Graph. Build once after loading; every
- * query is then O(1) or O(k) (k = result count).
- *
- * The whole index is built in one pass on construction. For graphpilot's own
- * code (50 symbols, 155 edges) build time is <1ms. For a 50k-symbol repo
- * we'd expect ~20ms — still negligible compared to a Claude Code round trip.
- */
-export class GraphIndex {
-  private readonly byNameLower: Map<string, SymbolRecord[]> = new Map();
-  private readonly byId: Map<string, SymbolRecord> = new Map();
-  /** Edges keyed by callee id — answers "who calls X?". */
-  private readonly callersOf: Map<string, CallEdge[]> = new Map();
-  /** Edges keyed by caller id — answers "what does X call?". */
-  private readonly calleesOf: Map<string, CallEdge[]> = new Map();
-
-  constructor(public readonly graph: Graph) {
-    for (const s of graph.symbols) {
-      this.byId.set(s.id, s);
-      const key = s.name.toLowerCase();
-      const list = this.byNameLower.get(key);
-      if (list) list.push(s);
-      else this.byNameLower.set(key, [s]);
-    }
-
-    for (const e of graph.edges) {
-      // callers index — only resolved edges have a toId
-      if (e.toId) {
-        const list = this.callersOf.get(e.toId);
-        if (list) list.push(e);
-        else this.callersOf.set(e.toId, [e]);
-      }
-      // callees index — every edge has a fromId
-      const list = this.calleesOf.get(e.fromId);
-      if (list) list.push(e);
-      else this.calleesOf.set(e.fromId, [e]);
-    }
-  }
-
-  /**
-   * Find symbols by name. Default behaviour is exact case-insensitive match;
-   * pass `substring: true` to enable substring search.
-   *
-   * Returns ranked roughly by "best first" — exact case match before
-   * case-folded matches.
-   */
-  findByName(query: string, opts: RecallOptions = {}): SymbolRecord[] {
-    const limit = Math.min(opts.limit ?? 10, HARD_RESULT_CAP);
-    if (!query) return [];
-
-    if (opts.substring) {
-      const q = query.toLowerCase();
-      const results: SymbolRecord[] = [];
-      for (const [name, syms] of this.byNameLower) {
-        if (!name.includes(q)) continue;
-        for (const s of syms) {
-          results.push(s);
-          if (results.length >= limit) return results;
-        }
-      }
-      return results;
-    }
-
-    // Exact case-insensitive — fast path through the map.
-    const candidates = this.byNameLower.get(query.toLowerCase()) ?? [];
-    if (candidates.length === 0) return [];
-
-    // Prefer exact case match first, then the rest.
-    const exact = candidates.filter((s) => s.name === query);
-    const rest = candidates.filter((s) => s.name !== query);
-    return [...exact, ...rest].slice(0, limit);
-  }
-
-  /** Look up a symbol by its id. Returns null if not found. */
-  findById(id: string): SymbolRecord | null {
-    return this.byId.get(id) ?? null;
-  }
-
-  /**
-   * Resolve a name (or id) to a unique symbol. Used by tools that take a
-   * "symbol" argument — accepts either a bare name or a full id.
-   *
-   * Ambiguity policy: if more than one symbol matches the name, returns the
-   * first one (same heuristic as the resolver). Caller can disambiguate by
-   * passing the full id.
-   */
-  resolveSymbol(nameOrId: string): SymbolRecord | null {
-    if (nameOrId.includes('#') && nameOrId.includes('@')) {
-      return this.findById(nameOrId);
-    }
-    const matches = this.findByName(nameOrId);
-    return matches[0] ?? null;
-  }
-
-  /** Edges where this symbol is the target — "who calls X?". */
-  callers(symbolId: string, opts: EdgeQueryOptions = {}): CallEdge[] {
-    const limit = Math.min(opts.limit ?? 50, HARD_EDGE_CAP);
-    return (this.callersOf.get(symbolId) ?? []).slice(0, limit);
-  }
-
-  /** Edges where this symbol is the source — "what does X call?". */
-  callees(symbolId: string, opts: EdgeQueryOptions = {}): CallEdge[] {
-    const limit = Math.min(opts.limit ?? 50, HARD_EDGE_CAP);
-    const all = this.calleesOf.get(symbolId) ?? [];
-    if (opts.includeUnresolved === false) {
-      return all.filter((e) => e.toId !== null).slice(0, limit);
-    }
-    return all.slice(0, limit);
-  }
-
-  /** Convenience: how many symbols / edges are indexed. */
-  get stats(): { symbols: number; edges: number; resolvedEdges: number } {
-    let resolved = 0;
-    for (const e of this.graph.edges) if (e.toId) resolved++;
-    return {
-      symbols: this.graph.symbols.length,
-      edges: this.graph.edges.length,
-      resolvedEdges: resolved,
-    };
-  }
-}

package/src/redact.ts

@@ -1,122 +0,0 @@
-/**
- * Secret-pattern redaction for symbol signatures before they're stored.
- *
- * Code occasionally contains literal secrets — `const API_KEY = "sk-..."`,
- * embedded JWTs, AWS access keys, GitHub tokens. When we extract a symbol's
- * signature line into graph.json, those literals come with it. We redact
- * them here so:
- *   1. The on-disk graph.json doesn't carry plaintext secrets
- *   2. The MCP tool output sent to the agent doesn't expose them either
- *
- * This is NOT a full secret scanner — it covers well-known fixed-prefix
- * formats. Determined leakage (custom-format secrets) will still escape,
- * but the common ones are covered.
- *
- * Pattern coverage and replacement tokens are intentionally short so a
- * signature stays readable after redaction.
- */
-
-interface SecretPattern {
-  pattern: RegExp;
-  replacement: string;
-  label: string;
-}
-
-const SECRET_PATTERNS: readonly SecretPattern[] = [
-  // PEM private-key headers — match the BEGIN line before generic long-token
-  // catches it, so we get the precise label.
-  {
-    pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/g,
-    replacement: '-----BEGIN ***REDACTED*** PRIVATE KEY-----',
-    label: 'pem-private-key',
-  },
-  // JSON Web Tokens: three base64url segments separated by dots.
-  {
-    pattern: /eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g,
-    replacement: '***JWT-REDACTED***',
-    label: 'jwt',
-  },
-  // OpenAI / Anthropic style API keys: `sk-` then 20+ alphanumerics.
-  // Also covers `sk-ant-...`, `sk-proj-...` etc.
-  {
-    pattern: /\bsk-[A-Za-z0-9_-]{20,}\b/g,
-    replacement: 'sk-***REDACTED***',
-    label: 'sk-token',
-  },
-  // GitHub personal access tokens.
-  { pattern: /\bghp_[A-Za-z0-9]{30,}\b/g, replacement: 'ghp_***REDACTED***', label: 'github-pat' },
-  // GitHub server tokens.
-  {
-    pattern: /\bghs_[A-Za-z0-9]{30,}\b/g,
-    replacement: 'ghs_***REDACTED***',
-    label: 'github-server',
-  },
-  // GitHub user / OAuth tokens.
-  {
-    pattern: /\bgho_[A-Za-z0-9]{30,}\b/g,
-    replacement: 'gho_***REDACTED***',
-    label: 'github-oauth',
-  },
-  // GitHub refresh tokens.
-  {
-    pattern: /\bghr_[A-Za-z0-9]{30,}\b/g,
-    replacement: 'ghr_***REDACTED***',
-    label: 'github-refresh',
-  },
-  // AWS access key IDs.
-  { pattern: /\bAKIA[0-9A-Z]{16}\b/g, replacement: 'AKIA***REDACTED***', label: 'aws-akia' },
-  // AWS short-term session tokens (less specific, but the leading prefix is unique).
-  { pattern: /\bASIA[0-9A-Z]{16}\b/g, replacement: 'ASIA***REDACTED***', label: 'aws-asia' },
-  // Slack tokens.
-  {
-    pattern: /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g,
-    replacement: 'xox*-***REDACTED***',
-    label: 'slack',
-  },
-  // Stripe live secret keys.
-  {
-    pattern: /\bsk_live_[A-Za-z0-9]{20,}\b/g,
-    replacement: 'sk_live_***REDACTED***',
-    label: 'stripe-live',
-  },
-  // Generic long high-entropy token inside a string literal.
-  // Heuristic: 32+ chars of alphanumeric / underscore / hyphen / equals,
-  // immediately surrounded by matching quotes. Keeps false positives down
-  // because random function names rarely live inside quotes.
-  {
-    pattern: /(["'])([A-Za-z0-9_+/=-]{40,})\1/g,
-    replacement: '$1***REDACTED-LONG-TOKEN***$1',
-    label: 'long-token-in-string',
-  },
-];
-
-/**
- * Run every secret pattern over the input string. Returns the redacted text.
- * Safe for any input length: regex operations are linear in input size.
- *
- * Order matters — more specific patterns run first so a JWT doesn't get
- * eaten by the generic long-token catch-all.
- */
-export function redactSecrets(text: string): string {
-  if (!text) return text;
-  let out = text;
-  for (const { pattern, replacement } of SECRET_PATTERNS) {
-    out = out.replace(pattern, replacement);
-  }
-  return out;
-}
-
-/**
- * Test helper / introspection: which patterns matched in this input?
- * Useful for diagnostics; not on a hot path.
- */
-export function detectSecrets(text: string): string[] {
-  if (!text) return [];
-  const hits: string[] = [];
-  for (const { pattern, label } of SECRET_PATTERNS) {
-    // Build a fresh regex from the source to avoid lastIndex state on /g.
-    const fresh = new RegExp(pattern.source, pattern.flags);
-    if (fresh.test(text)) hits.push(label);
-  }
-  return hits;
-}

package/src/storage.ts

@@ -1,115 +0,0 @@
-import { createHash } from 'node:crypto';
-import { homedir } from 'node:os';
-import { join } from 'node:path';
-import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync, renameSync } from 'node:fs';
-import type { SymbolRecord } from './symbols.js';
-import type { CallEdge } from './edges.js';
-import { validateGraph } from './graph-schema.js';
-
-const isWindows = process.platform === 'win32';
-
-export interface Graph {
-  version: 1;
-  repoId: string;
-  rootPath: string;
-  indexedAt: string;
-  filesIndexed: number;
-  symbolCount: number;
-  edgeCount: number;
-  symbols: SymbolRecord[];
-  edges: CallEdge[];
-  /**
-   * Optional git provenance — set when the indexed root lives inside a
-   * git worktree. Both fields may be null even within a git repo (e.g.
-   * detached HEAD has no branch; an empty repo has no SHA). Older
-   * graph.json files written before the v0.1.5 pivot won't have these
-   * fields; the schema validator treats them as optional so old graphs
-   * still load.
-   */
-  indexedSha?: string | null;
-  indexedBranch?: string | null;
-}
-
-export function repoIdFor(absRootPath: string): string {
-  return createHash('sha256').update(absRootPath).digest('hex').slice(0, 16);
-}
-
-export function repoDir(absRootPath: string): string {
-  return join(homedir(), '.graphpilot', repoIdFor(absRootPath));
-}
-
-export function graphPath(absRootPath: string): string {
-  return join(repoDir(absRootPath), 'graph.json');
-}
-
-export function saveGraph(graph: Graph): string {
-  const dir = repoDir(graph.rootPath);
-  // T7 defence: 0700 dir + 0600 file so other users on shared machines can't
-  // read the index. The mkdir/writeFileSync `mode` option only applies on
-  // creation, so we explicitly chmod afterwards to fix permissions on any
-  // pre-existing files (e.g. an index written before this protection landed).
-  // On Windows these modes are silently ignored, which is fine — NTFS ACLs
-  // are handled by the user profile boundary.
-  mkdirSync(dir, { recursive: true, mode: 0o700 });
-  if (!isWindows) chmodSync(dir, 0o700);
-  const path = graphPath(graph.rootPath);
-
-  // Atomic write — write to a sibling .tmp file and rename. Crash-safe:
-  // a partial write never produces a corrupt graph.json that would later
-  // fail T4's schema validator and force a full re-index. Defends watch
-  // mode (which writes many times) against ungraceful shutdowns.
-  const tmpPath = path + '.tmp';
-  writeFileSync(tmpPath, JSON.stringify(graph, null, 2), {
-    encoding: 'utf8',
-    mode: 0o600,
-  });
-  if (!isWindows) chmodSync(tmpPath, 0o600);
-  renameSync(tmpPath, path);
-  return path;
-}
-
-/**
- * Load and validate a graph from disk. Returns null if the file is missing,
- * unparseable, has a wrong schema version, or fails structural validation.
- *
- * T4 defence: anything from disk is untrusted. We re-parse and re-shape
- * every field before exposing the result to query / MCP layers. String
- * fields are sanitized (control chars stripped, lengths capped) so a
- * crafted graph.json can't smuggle prompt-injection payloads or fake JSON
- * Lines into tool output.
- *
- * Validation errors are written to stderr for diagnostics. The function
- * never throws on bad data — it returns null so the MCP tool layer can
- * surface "no index" cleanly.
- */
-export function loadGraph(absRootPath: string): Graph | null {
-  const path = graphPath(absRootPath);
-  if (!existsSync(path)) return null;
-
-  let raw: string;
-  try {
-    raw = readFileSync(path, 'utf8');
-  } catch {
-    return null;
-  }
-
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    process.stderr.write(`[graphpilot] graph.json is not valid JSON: ${path}\n`);
-    return null;
-  }
-
-  const errors: string[] = [];
-  const validated = validateGraph(parsed, errors);
-  if (!validated) {
-    process.stderr.write(
-      `[graphpilot] graph.json failed schema validation: ${path}\n` +
-        errors.map((e) => `  - ${e}`).join('\n') +
-        '\n',
-    );
-    return null;
-  }
-  return validated;
-}