clast-ai 0.1.0

package/skills/clast-explore/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: clast-explore
+description: >
+  Use when exploring or understanding code structure: finding functions, tracing call graphs,
+  understanding symbol context before editing, or generating documentation. Triggers when Claude
+  needs to navigate a codebase, find definitions, understand relationships between functions,
+  or prepare context for code modifications.
+version: 0.1.0
+---
+
+# Clast Code Intelligence
+
+This project has Clast AST indexing active. Before reading entire files or using grep to find
+code, prefer using Clast tools for faster, more structured results:
+
+## Available Tools
+
+1. **clast_search** — Find functions, classes, methods by name pattern.
+   Use this BEFORE grep when looking for a symbol definition.
+
+2. **clast_get_context** — Get full context for a symbol: definition, comments, who calls it,
+   what it calls. Use this BEFORE reading a file to understand a specific function or class.
+
+3. **clast_call_graph** — Trace the call chain: what calls a function (callers) and what it
+   calls (callees). Use this before refactoring to understand impact.
+
+4. **clast_file_summary** — Get all symbols in a file grouped by type. Use this instead of
+   reading a whole file when you just need to understand its structure.
+
+5. **clast_status** — Check if the index is up to date.
+
+6. **clast_reindex** — Force re-index if data seems stale.
+
+7. **clast_comment** — Get or generate documentation for a function/class.
+
+## Workflow Tips
+
+- When asked to edit a function: use `clast_get_context` first to understand it, then edit.
+- When asked to refactor: use `clast_call_graph` to understand the blast radius.
+- When exploring unfamiliar code: use `clast_file_summary` on key files.
+- When adding features: use `clast_search` to find related existing code.

package/src/config/defaults.ts

@@ -0,0 +1,61 @@
+export interface ClastConfig {
+  languages: string[];
+  ignoredPaths: string[];
+  dbPath: string;
+  llm: {
+    endpoint: string;
+    model: string;
+    apiKey: string;
+    maxConcurrent: number;
+    alwaysGenerate: boolean;
+  };
+  watch: {
+    debounceMs: number;
+    enabled: boolean;
+  };
+  maxBodySize: number;
+}
+
+export const DEFAULT_CONFIG: ClastConfig = {
+  languages: [
+    'typescript',
+    'javascript',
+    'python',
+    'java',
+    'csharp',
+    'go',
+    'rust',
+    'c',
+    'cpp',
+    'ruby',
+    'php',
+  ],
+  ignoredPaths: [
+    'node_modules',
+    '.git',
+    'dist',
+    'build',
+    'out',
+    '__pycache__',
+    '.venv',
+    'venv',
+    '.clast',
+    'vendor',
+    'target',
+    '.next',
+    'coverage',
+  ],
+  dbPath: '.clast/clast.db',
+  llm: {
+    endpoint: 'http://localhost:11434/v1',
+    model: '',
+    apiKey: '',
+    maxConcurrent: 3,
+    alwaysGenerate: false,
+  },
+  watch: {
+    debounceMs: 300,
+    enabled: true,
+  },
+  maxBodySize: 2000,
+};

package/src/config/index.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFAULT_CONFIG, type ClastConfig } from './defaults.js';
+
+const LlmConfigSchema = z.object({
+  endpoint: z.string().default(DEFAULT_CONFIG.llm.endpoint),
+  model: z.string().default(DEFAULT_CONFIG.llm.model),
+  apiKey: z.string().default(DEFAULT_CONFIG.llm.apiKey),
+  maxConcurrent: z.number().int().min(1).max(10).default(DEFAULT_CONFIG.llm.maxConcurrent),
+  alwaysGenerate: z.boolean().default(DEFAULT_CONFIG.llm.alwaysGenerate),
+});
+
+const WatchConfigSchema = z.object({
+  debounceMs: z.number().int().min(50).max(5000).default(DEFAULT_CONFIG.watch.debounceMs),
+  enabled: z.boolean().default(DEFAULT_CONFIG.watch.enabled),
+});
+
+const ClastConfigSchema = z.object({
+  languages: z.array(z.string()).default(DEFAULT_CONFIG.languages),
+  ignoredPaths: z.array(z.string()).default(DEFAULT_CONFIG.ignoredPaths),
+  dbPath: z.string().default(DEFAULT_CONFIG.dbPath),
+  llm: LlmConfigSchema.default(DEFAULT_CONFIG.llm),
+  watch: WatchConfigSchema.default(DEFAULT_CONFIG.watch),
+  maxBodySize: z.number().int().min(100).max(50000).default(DEFAULT_CONFIG.maxBodySize),
+});
+
+export type { ClastConfig } from './defaults.js';
+
+export function loadConfig(projectRoot: string): ClastConfig {
+  const candidates = [
+    join(projectRoot, 'clast.config.json'),
+    join(projectRoot, '.claude', 'clast.config.json'),
+  ];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      try {
+        const raw = JSON.parse(readFileSync(candidate, 'utf-8'));
+        return ClastConfigSchema.parse(raw) as ClastConfig;
+      } catch (err) {
+        console.error(`[clast] Failed to parse config at ${candidate}:`, err);
+      }
+    }
+  }
+
+  return ClastConfigSchema.parse({}) as ClastConfig;
+}
+
+export function resolveDbPath(projectRoot: string, config: ClastConfig): string {
+  if (config.dbPath.startsWith('/') || config.dbPath.match(/^[a-zA-Z]:\\/)) {
+    return config.dbPath;
+  }
+  return join(projectRoot, config.dbPath);
+}

package/src/db/index.ts

@@ -0,0 +1,63 @@
+import initSqlJs, { type Database } from 'sql.js';
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { initializeSchema } from './schema.js';
+import { Queries } from './queries.js';
+
+export class ClastDatabase {
+  private db: Database;
+  private dbPath: string;
+  private saveTimer: ReturnType<typeof setInterval> | null = null;
+  public queries: Queries;
+
+  private constructor(db: Database, dbPath: string) {
+    this.db = db;
+    this.dbPath = dbPath;
+    initializeSchema(this.db);
+    this.queries = new Queries(this.db);
+
+    // Auto-save every 10 seconds
+    this.saveTimer = setInterval(() => this.save(), 10000);
+  }
+
+  static async open(dbPath: string): Promise<ClastDatabase> {
+    mkdirSync(dirname(dbPath), { recursive: true });
+
+    const SQL = await initSqlJs();
+
+    let db: Database;
+    if (existsSync(dbPath)) {
+      const buffer = readFileSync(dbPath);
+      db = new SQL.Database(buffer);
+    } else {
+      db = new SQL.Database();
+    }
+
+    return new ClastDatabase(db, dbPath);
+  }
+
+  save(): void {
+    try {
+      const data = this.db.export();
+      writeFileSync(this.dbPath, Buffer.from(data));
+    } catch (err) {
+      console.error('[clast] Failed to save database:', err);
+    }
+  }
+
+  close(): void {
+    if (this.saveTimer) {
+      clearInterval(this.saveTimer);
+      this.saveTimer = null;
+    }
+    this.save();
+    this.db.close();
+  }
+
+  get raw(): Database {
+    return this.db;
+  }
+}
+
+export { Queries } from './queries.js';
+export type { FileRow, AstNodeRow, CallEdgeRow, CommentRow, StatusRow } from './types.js';

package/src/db/queries.ts

@@ -0,0 +1,332 @@
+import type { Database } from 'sql.js';
+import type { FileRow, AstNodeRow, CallEdgeRow, CommentRow, StatusRow } from './types.js';
+
+export class Queries {
+  private db: Database;
+
+  constructor(db: Database) {
+    this.db = db;
+  }
+
+  private run(sql: string, params: unknown[] = []): void {
+    this.db.run(sql, params as (string | number | null | Uint8Array)[]);
+  }
+
+  private get<T>(sql: string, params: unknown[] = []): T | undefined {
+    const result = this.db.exec(sql, params as (string | number | null | Uint8Array)[]);
+    if (result.length === 0 || result[0]!.values.length === 0) return undefined;
+    const columns = result[0]!.columns;
+    const values = result[0]!.values[0]!;
+    const obj: Record<string, unknown> = {};
+    for (let i = 0; i < columns.length; i++) {
+      obj[columns[i]!] = values[i];
+    }
+    return obj as T;
+  }
+
+  private all<T>(sql: string, params: unknown[] = []): T[] {
+    const result = this.db.exec(sql, params as (string | number | null | Uint8Array)[]);
+    if (result.length === 0) return [];
+    const columns = result[0]!.columns;
+    return result[0]!.values.map(values => {
+      const obj: Record<string, unknown> = {};
+      for (let i = 0; i < columns.length; i++) {
+        obj[columns[i]!] = values[i];
+      }
+      return obj as T;
+    });
+  }
+
+  private getLastInsertId(): number {
+    const result = this.db.exec('SELECT last_insert_rowid() as id');
+    if (result.length > 0 && result[0]!.values.length > 0) {
+      return Number(result[0]!.values[0]![0]);
+    }
+    return 0;
+  }
+
+  // --- File operations ---
+
+  upsertFile(filePath: string, hash: string, language: string, nodeCount: number): void {
+    this.run(
+      `INSERT OR REPLACE INTO files (file_path, hash, language, last_indexed, node_count)
+       VALUES (?, ?, ?, ?, ?)`,
+      [filePath, hash, language, Date.now(), nodeCount]
+    );
+  }
+
+  deleteFile(filePath: string): void {
+    // Manually cascade since sql.js foreign key cascade can be unreliable
+    this.run(`DELETE FROM comments WHERE node_id IN (SELECT id FROM ast_nodes WHERE file_path = ?)`, [filePath]);
+    this.run(`DELETE FROM call_edges WHERE caller_id IN (SELECT id FROM ast_nodes WHERE file_path = ?)`, [filePath]);
+    this.run(`DELETE FROM call_edges WHERE callee_id IN (SELECT id FROM ast_nodes WHERE file_path = ?)`, [filePath]);
+    this.run(`DELETE FROM ast_nodes WHERE file_path = ?`, [filePath]);
+    this.run(`DELETE FROM files WHERE file_path = ?`, [filePath]);
+  }
+
+  getFileHash(filePath: string): string | null {
+    const row = this.get<{ hash: string }>(`SELECT hash FROM files WHERE file_path = ?`, [filePath]);
+    return row?.hash ?? null;
+  }
+
+  getAllFiles(): FileRow[] {
+    return this.all<FileRow>(`SELECT * FROM files`);
+  }
+
+  // --- Node operations ---
+
+  insertNode(node: Omit<AstNodeRow, 'id'>): number {
+    this.run(
+      `INSERT INTO ast_nodes (file_path, name, type, signature, start_line, end_line, start_col, end_col, parent_id, language, body_text)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        node.file_path, node.name, node.type, node.signature,
+        node.start_line, node.end_line, node.start_col, node.end_col,
+        node.parent_id, node.language, node.body_text,
+      ]
+    );
+    return this.getLastInsertId();
+  }
+
+  insertNodes(nodes: Omit<AstNodeRow, 'id'>[]): number[] {
+    const ids: number[] = [];
+    this.run('BEGIN TRANSACTION');
+    try {
+      for (const node of nodes) {
+        ids.push(this.insertNode(node));
+      }
+      this.run('COMMIT');
+    } catch (err) {
+      this.run('ROLLBACK');
+      throw err;
+    }
+    return ids;
+  }
+
+  getNodeById(id: number): AstNodeRow | undefined {
+    return this.get<AstNodeRow>(`SELECT * FROM ast_nodes WHERE id = ?`, [id]);
+  }
+
+  getNodeByName(name: string): AstNodeRow[] {
+    return this.all<AstNodeRow>(
+      `SELECT * FROM ast_nodes WHERE name = ? ORDER BY file_path, start_line`,
+      [name]
+    );
+  }
+
+  getNodesByFile(filePath: string): AstNodeRow[] {
+    return this.all<AstNodeRow>(
+      `SELECT * FROM ast_nodes WHERE file_path = ? ORDER BY start_line`,
+      [filePath]
+    );
+  }
+
+  searchNodes(query: string, type?: string, limit: number = 20): AstNodeRow[] {
+    const pattern = `%${query}%`;
+    if (type) {
+      return this.all<AstNodeRow>(
+        `SELECT * FROM ast_nodes WHERE name LIKE ? AND type = ? LIMIT ?`,
+        [pattern, type, limit]
+      );
+    }
+    return this.all<AstNodeRow>(
+      `SELECT * FROM ast_nodes WHERE name LIKE ? LIMIT ?`,
+      [pattern, limit]
+    );
+  }
+
+  // --- Edge operations ---
+
+  insertEdge(edge: Omit<CallEdgeRow, 'id'>): number {
+    this.run(
+      `INSERT INTO call_edges (caller_id, callee_id, callee_name, file_path, line)
+       VALUES (?, ?, ?, ?, ?)`,
+      [edge.caller_id, edge.callee_id, edge.callee_name, edge.file_path, edge.line]
+    );
+    return this.getLastInsertId();
+  }
+
+  insertEdges(edges: Omit<CallEdgeRow, 'id'>[]): void {
+    this.run('BEGIN TRANSACTION');
+    try {
+      for (const edge of edges) {
+        this.insertEdge(edge);
+      }
+      this.run('COMMIT');
+    } catch (err) {
+      this.run('ROLLBACK');
+      throw err;
+    }
+  }
+
+  getCallersOf(nameOrId: string | number, depth: number = 2): AstNodeRow[] {
+    const whereClause = typeof nameOrId === 'number'
+      ? 'callee_id = ?'
+      : 'callee_name = ?';
+
+    const sql = `
+      WITH RECURSIVE caller_chain(id, depth) AS (
+        SELECT caller_id, 1
+        FROM call_edges
+        WHERE ${whereClause}
+        UNION
+        SELECT ce.caller_id, cc.depth + 1
+        FROM call_edges ce
+        JOIN caller_chain cc ON ce.callee_id = cc.id
+        WHERE cc.depth < ?
+      )
+      SELECT DISTINCT an.* FROM ast_nodes an
+      JOIN caller_chain cc ON an.id = cc.id
+      ORDER BY an.file_path, an.start_line
+    `;
+    return this.all<AstNodeRow>(sql, [nameOrId, depth]);
+  }
+
+  getCalleesOf(nameOrId: string | number, depth: number = 2): AstNodeRow[] {
+    const whereClause = typeof nameOrId === 'number'
+      ? 'an.id = ?'
+      : 'an.name = ?';
+
+    const sql = `
+      WITH RECURSIVE callee_chain(id, name, depth) AS (
+        SELECT ce.callee_id, ce.callee_name, 1
+        FROM call_edges ce
+        JOIN ast_nodes an ON ce.caller_id = an.id
+        WHERE ${whereClause}
+        UNION
+        SELECT ce2.callee_id, ce2.callee_name, cc.depth + 1
+        FROM call_edges ce2
+        JOIN callee_chain cc ON ce2.caller_id = cc.id
+        WHERE cc.depth < ? AND cc.id IS NOT NULL
+      )
+      SELECT DISTINCT an.* FROM ast_nodes an
+      JOIN callee_chain cc ON an.id = cc.id
+      WHERE cc.id IS NOT NULL
+      ORDER BY an.file_path, an.start_line
+    `;
+    return this.all<AstNodeRow>(sql, [nameOrId, depth]);
+  }
+
+  getCallEdgesForNode(nodeId: number): { outgoing: CallEdgeRow[]; incoming: CallEdgeRow[] } {
+    const outgoing = this.all<CallEdgeRow>(
+      `SELECT * FROM call_edges WHERE caller_id = ?`,
+      [nodeId]
+    );
+    const incoming = this.all<CallEdgeRow>(
+      `SELECT * FROM call_edges WHERE callee_id = ?`,
+      [nodeId]
+    );
+    return { outgoing, incoming };
+  }
+
+  // --- Comment operations ---
+
+  insertComment(nodeId: number, text: string, source: 'original' | 'generated'): number {
+    this.run(
+      `INSERT INTO comments (node_id, text, source, generated_at)
+       VALUES (?, ?, ?, ?)`,
+      [nodeId, text, source, source === 'generated' ? Date.now() : null]
+    );
+    return this.getLastInsertId();
+  }
+
+  getCommentsForNode(nodeId: number): CommentRow[] {
+    return this.all<CommentRow>(`SELECT * FROM comments WHERE node_id = ?`, [nodeId]);
+  }
+
+  deleteCommentsBySource(nodeId: number, source: 'original' | 'generated'): void {
+    this.run(`DELETE FROM comments WHERE node_id = ? AND source = ?`, [nodeId, source]);
+  }
+
+  // --- Context (combined) ---
+
+  getNodeWithContext(name: string): {
+    nodes: AstNodeRow[];
+    comments: CommentRow[];
+    callers: AstNodeRow[];
+    callees: AstNodeRow[];
+  } {
+    const nodes = this.getNodeByName(name);
+    if (nodes.length === 0) {
+      return { nodes: [], comments: [], callers: [], callees: [] };
+    }
+
+    const allComments: CommentRow[] = [];
+    for (const node of nodes) {
+      allComments.push(...this.getCommentsForNode(node.id));
+    }
+
+    const callers = this.getCallersOf(name, 1);
+    const callees = this.getCalleesOf(name, 1);
+
+    return { nodes, comments: allComments, callers, callees };
+  }
+
+  // --- Status ---
+
+  getStatus(): StatusRow {
+    const result = this.get<StatusRow>(`
+      SELECT
+        (SELECT COUNT(*) FROM files) as files_indexed,
+        (SELECT COUNT(*) FROM ast_nodes) as total_nodes,
+        (SELECT COUNT(*) FROM call_edges) as total_edges,
+        (SELECT COUNT(*) FROM comments) as total_comments,
+        (SELECT MAX(last_indexed) FROM files) as last_indexed
+    `);
+    return result ?? {
+      files_indexed: 0,
+      total_nodes: 0,
+      total_edges: 0,
+      total_comments: 0,
+      last_indexed: null,
+    };
+  }
+
+  // --- Bulk operations ---
+
+  deleteNodesForFile(filePath: string): void {
+    this.run(`DELETE FROM comments WHERE node_id IN (SELECT id FROM ast_nodes WHERE file_path = ?)`, [filePath]);
+    this.run(`DELETE FROM call_edges WHERE caller_id IN (SELECT id FROM ast_nodes WHERE file_path = ?)`, [filePath]);
+    this.run(`DELETE FROM ast_nodes WHERE file_path = ?`, [filePath]);
+  }
+
+  resolveEdges(): number {
+    // Count unresolved before
+    const before = this.get<{ cnt: number }>(
+      `SELECT COUNT(*) as cnt FROM call_edges WHERE callee_id IS NULL`
+    );
+    const beforeCount = before?.cnt ?? 0;
+
+    this.run(`
+      UPDATE call_edges
+      SET callee_id = (
+        SELECT an.id FROM ast_nodes an
+        WHERE an.name = call_edges.callee_name
+        LIMIT 1
+      )
+      WHERE callee_id IS NULL
+    `);
+
+    const after = this.get<{ cnt: number }>(
+      `SELECT COUNT(*) as cnt FROM call_edges WHERE callee_id IS NULL`
+    );
+    const afterCount = after?.cnt ?? 0;
+
+    return beforeCount - afterCount;
+  }
+
+  getNodesWithoutComments(limit: number = 100): AstNodeRow[] {
+    return this.all<AstNodeRow>(`
+      SELECT an.* FROM ast_nodes an
+      LEFT JOIN comments c ON an.id = c.node_id
+      WHERE c.id IS NULL
+        AND an.type IN ('function', 'method', 'class', 'interface', 'struct', 'trait')
+      LIMIT ?
+    `, [limit]);
+  }
+
+  /** Flush the in-memory database to a Uint8Array for saving to disk. */
+  export(): Uint8Array {
+    return this.db.export();
+  }
+}

package/src/db/schema.ts

@@ -0,0 +1,106 @@
+import type { Database } from 'sql.js';
+
+const SCHEMA_VERSION = 1;
+
+const CREATE_TABLES = `
+  CREATE TABLE IF NOT EXISTS _clast_meta (
+    key TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+  );
+
+  CREATE TABLE IF NOT EXISTS files (
+    file_path TEXT PRIMARY KEY,
+    hash TEXT NOT NULL,
+    language TEXT NOT NULL,
+    last_indexed INTEGER NOT NULL,
+    node_count INTEGER NOT NULL DEFAULT 0
+  );
+
+  CREATE TABLE IF NOT EXISTS ast_nodes (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    file_path TEXT NOT NULL,
+    name TEXT NOT NULL,
+    type TEXT NOT NULL,
+    signature TEXT NOT NULL DEFAULT '',
+    start_line INTEGER NOT NULL,
+    end_line INTEGER NOT NULL,
+    start_col INTEGER NOT NULL,
+    end_col INTEGER NOT NULL,
+    parent_id INTEGER,
+    language TEXT NOT NULL,
+    body_text TEXT NOT NULL DEFAULT '',
+    FOREIGN KEY (file_path) REFERENCES files(file_path) ON DELETE CASCADE,
+    FOREIGN KEY (parent_id) REFERENCES ast_nodes(id) ON DELETE CASCADE
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_nodes_name ON ast_nodes(name);
+  CREATE INDEX IF NOT EXISTS idx_nodes_type ON ast_nodes(type);
+  CREATE INDEX IF NOT EXISTS idx_nodes_file ON ast_nodes(file_path);
+  CREATE INDEX IF NOT EXISTS idx_nodes_name_type ON ast_nodes(name, type);
+
+  CREATE TABLE IF NOT EXISTS call_edges (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    caller_id INTEGER NOT NULL,
+    callee_id INTEGER,
+    callee_name TEXT NOT NULL,
+    file_path TEXT NOT NULL,
+    line INTEGER NOT NULL,
+    FOREIGN KEY (caller_id) REFERENCES ast_nodes(id) ON DELETE CASCADE,
+    FOREIGN KEY (callee_id) REFERENCES ast_nodes(id) ON DELETE SET NULL
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_edges_caller ON call_edges(caller_id);
+  CREATE INDEX IF NOT EXISTS idx_edges_callee ON call_edges(callee_id);
+  CREATE INDEX IF NOT EXISTS idx_edges_callee_name ON call_edges(callee_name);
+
+  CREATE TABLE IF NOT EXISTS comments (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    node_id INTEGER NOT NULL,
+    text TEXT NOT NULL,
+    source TEXT NOT NULL CHECK(source IN ('original', 'generated')),
+    generated_at INTEGER,
+    FOREIGN KEY (node_id) REFERENCES ast_nodes(id) ON DELETE CASCADE
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_comments_node ON comments(node_id);
+`;
+
+export function initializeSchema(db: Database): void {
+  db.run('PRAGMA foreign_keys = ON');
+
+  const currentVersion = getSchemaVersion(db);
+
+  if (currentVersion < SCHEMA_VERSION) {
+    // sql.js doesn't support multi-statement exec with CREATE TABLE IF NOT EXISTS well,
+    // so we split and execute each statement
+    const statements = CREATE_TABLES.split(';')
+      .map(s => s.trim())
+      .filter(s => s.length > 0);
+
+    for (const stmt of statements) {
+      db.run(stmt);
+    }
+    setSchemaVersion(db, SCHEMA_VERSION);
+  }
+}
+
+function getSchemaVersion(db: Database): number {
+  try {
+    const result = db.exec(
+      `SELECT value FROM _clast_meta WHERE key = 'schema_version'`
+    );
+    if (result.length > 0 && result[0]!.values.length > 0) {
+      return parseInt(String(result[0]!.values[0]![0]), 10);
+    }
+    return 0;
+  } catch {
+    return 0;
+  }
+}
+
+function setSchemaVersion(db: Database, version: number): void {
+  db.run(
+    `INSERT OR REPLACE INTO _clast_meta (key, value) VALUES ('schema_version', ?)`,
+    [String(version)]
+  );
+}

package/src/db/types.ts

@@ -0,0 +1,47 @@
+export interface FileRow {
+  file_path: string;
+  hash: string;
+  language: string;
+  last_indexed: number;
+  node_count: number;
+}
+
+export interface AstNodeRow {
+  id: number;
+  file_path: string;
+  name: string;
+  type: string;
+  signature: string;
+  start_line: number;
+  end_line: number;
+  start_col: number;
+  end_col: number;
+  parent_id: number | null;
+  language: string;
+  body_text: string;
+}
+
+export interface CallEdgeRow {
+  id: number;
+  caller_id: number;
+  callee_id: number | null;
+  callee_name: string;
+  file_path: string;
+  line: number;
+}
+
+export interface CommentRow {
+  id: number;
+  node_id: number;
+  text: string;
+  source: 'original' | 'generated';
+  generated_at: number | null;
+}
+
+export interface StatusRow {
+  files_indexed: number;
+  total_nodes: number;
+  total_edges: number;
+  total_comments: number;
+  last_indexed: number | null;
+}