feed-the-machine 1.0.0 → 1.2.0

package/ftm-map/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: ftm-map
+description: Persistent code knowledge graph powered by tree-sitter and SQLite with FTS5 full-text search. Builds structural dependency graphs for blast radius analysis, dependency chains, and keyword search. Use when user asks "what breaks if I change X", "blast radius", "what depends on", "where do we handle", "map codebase", "index project", "what calls", "dependency chain", "ftm-map".
+---
+
+# ftm-map
+
+Persistent code knowledge graph powered by tree-sitter and SQLite with FTS5 full-text search. Parses the local codebase into a structural dependency graph stored in `.ftm-map/map.db`, then answers structural queries (blast radius, dependency chains, symbol lookup) and keyword searches without re-reading the source tree on every question.
+
+## Events
+
+### Emits
+- `map_updated` — when the graph database has been updated (bootstrap or incremental)
+  - Payload: `{ project_path, symbols_count, edges_count, files_parsed, duration_ms, mode }`
+- `task_completed` — when any ftm-map operation finishes
+
+### Listens To
+- `code_committed` — run incremental index on changed files, then emit `map_updated`
+- `task_received` — begin bootstrap or query when ftm-mind routes a mapping/search request
+
+## Config Read
+
+Read `~/.claude/ftm-config.yml`:
+- Check `skills.ftm-map.enabled` (default: true)
+- Use `execution` model from active profile for indexing agents
+
+## Blackboard Read
+
+On startup, load context from the FTM blackboard:
+1. Load `~/.claude/ftm-blackboard/context.json`
+2. Filter experiences by `task_type: "map"`
+3. Load matching experience files to inform index scope and query routing
+4. Check for prior bootstrap records to determine if incremental mode is appropriate
+
+## Mode Detection
+
+Three modes, detected from request context:
+
+```
+Bootstrap:    "map this codebase" / "index this project" / no map.db exists yet
+              Full scan of all source files. Builds graph from scratch.
+
+Incremental:  Triggered by code_committed event or PostToolUse hook
+              Parses only changed files and updates their graph entries.
+
+Query:        Structural or keyword question about existing graph
+              Detects query type and runs appropriate script.
+```
+
+If `.ftm-map/map.db` does not exist when a query arrives, fall back to offering bootstrap (see Graceful Degradation below).
+
+## Mode 1: Bootstrap (full scan)
+
+Trigger: user says "map this codebase" or "index this project", or `.ftm-map/map.db` does not yet exist.
+
+1. Run `ftm-map/scripts/setup.sh` to ensure virtualenv and tree-sitter dependencies are installed
+2. Run `ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/index.py --bootstrap <project_root>`
+3. Capture and report stats from stdout:
+   - Files parsed
+   - Symbols found
+   - Edges created
+   - Time elapsed
+4. Emit `map_updated` with `mode: "bootstrap"`
+
+Example invocation:
+```
+ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/index.py --bootstrap .
+```
+
+## Mode 2: Incremental (post-commit)
+
+Trigger: `code_committed` event fires, or PostToolUse hook detects a write to a source file.
+
+1. Get changed files:
+   ```
+   git diff --name-only HEAD~1
+   ```
+2. Filter to source files only (skip docs, configs, lockfiles)
+3. Run incremental index on changed files:
+   ```
+   ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/index.py --incremental --files <file1> <file2> ...
+   ```
+4. Emit `map_updated` with `mode: "incremental"` and count of updated entries
+
+## Mode 3: Query (answer structural and search questions)
+
+Trigger: user asks a structural or keyword question about the codebase.
+
+### Query Type Detection
+
+| User says | Query type | Script flag |
+|-----------|-----------|-------------|
+| "what breaks if I change X" | blast radius | `--blast-radius X` |
+| "blast radius of X" | blast radius | `--blast-radius X` |
+| "what depends on X" | dependency chain | `--deps X` |
+| "what calls X" | dependency chain (callers) | `--deps X` |
+| "where do we handle X" | FTS5 keyword search | `--search "X"` |
+| "find X in the codebase" | FTS5 keyword search | `--search "X"` |
+| "tell me about function X" | symbol info | `--info X` |
+| "show dependencies for X" | dependency chain | `--deps X` |
+
+### Execution
+
+Run the appropriate query script with the venv python:
+```
+ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/query.py --blast-radius <symbol>
+ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/query.py --deps <symbol>
+ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/query.py --search "<keywords>"
+ftm-map/scripts/.venv/bin/python3 ftm-map/scripts/query.py --info <symbol>
+```
+
+### Output Formatting
+
+Scripts return JSON. Render as readable markdown:
+
+**Blast radius** — tree of affected symbols with file paths and line numbers:
+```
+Blast radius of `authenticateUser`:
+  direct callers (3):
+    • loginHandler       src/handlers/auth.ts:42
+    • refreshSession     src/handlers/session.ts:17
+    • testAuthFlow       src/tests/auth.test.ts:88
+  transitive (5):
+    • routeMiddleware    src/middleware/index.ts:12
+    ...
+```
+
+**Dependency chain** — ordered list of dependencies (callee direction):
+```
+Dependencies of `authenticateUser`:
+  1. validateToken       src/auth/tokens.ts:8
+  2. decodeJWT           src/auth/jwt.ts:22
+  3. createSession       src/auth/session.ts:45
+  4. storeSession        src/auth/session.ts:67
+```
+
+**FTS5 search** — BM25-ranked list with file:line references:
+```
+Results for "rate limit" (6 matches, ranked by relevance):
+  1. applyRateLimit      src/middleware/ratelimit.ts:14      score: 0.94
+  2. RateLimitConfig     src/config/types.ts:88              score: 0.81
+  3. checkRateLimit      src/handlers/base.ts:203            score: 0.77
+  ...
+```
+
+**Symbol info** — full details card:
+```
+Symbol: authenticateUser
+  Kind:       function
+  File:       src/auth/index.ts:34
+  Signature:  authenticateUser(token: string, opts?: AuthOptions) → Promise<Session>
+  Callers:    3 direct, 5 transitive
+  Callees:    validateToken, decodeJWT, createSession
+  Dependents: 8 symbols total
+```
+
+## Graceful Degradation
+
+If `.ftm-map/map.db` does not exist when a query is requested:
+
+1. Explain that the graph has not been indexed yet
+2. Offer to bootstrap: "Run `ftm-map bootstrap` to index this codebase?"
+3. If user confirms, switch to Bootstrap mode immediately
+4. Do not attempt to answer structural queries by reading source files directly — the graph is the source of truth for structural questions
+
+## Python Script Interface
+
+All heavy lifting is done by Python scripts in `ftm-map/scripts/`. The skill orchestrates: detects mode, runs the right script with venv python, formats the output.
+
+| Script | Purpose |
+|--------|---------|
+| `setup.sh` | Creates virtualenv, installs tree-sitter and dependencies |
+| `db.py` | SQLite schema, CRUD operations, graph traversal queries |
+| `parser.py` | tree-sitter parsing and symbol/edge extraction |
+| `index.py` | Full bootstrap scan and incremental file indexing |
+| `query.py` | Blast radius, dependency chain, FTS5 keyword search, symbol info |
+| `views.py` | INTENT.md and .mmd generation from graph data |
+
+Always use the venv python — never the system python — to ensure tree-sitter bindings are available:
+```
+ftm-map/scripts/.venv/bin/python3 <script> <args>
+```
+
+## Integration Points
+
+**ftm-intent** may call ftm-map to retrieve caller/callee relationships when writing the `Relationships` field of INTENT.md entries. ftm-map returns structured JSON that ftm-intent formats into human-readable relationship text.
+
+**ftm-diagram** may call ftm-map to retrieve the dependency graph for a module when generating DIAGRAM.mmd files. ftm-map returns edge data that ftm-diagram renders as mermaid nodes and edges.
+
+Both integrations use `query.py --deps` and `query.py --info` to retrieve graph data without re-parsing source.
+
+## Blackboard Write
+
+After `map_updated` or session end:
+1. Update `~/.claude/ftm-blackboard/context.json` with map session summary
+2. Write experience file: `~/.claude/ftm-blackboard/experiences/map-[timestamp].json`
+   - Fields: project_path, mode, symbols_count, edges_count, files_parsed, duration_ms
+3. Update `~/.claude/ftm-blackboard/index.json` with new experience entry
+4. Emit `task_completed` event
+
+## Rules
+
+- NEVER stop to ask for input. Make decisions and keep going.
+- ALWAYS commit after completing with a clear message.
+- ALWAYS review after commit: run `git diff HEAD~1`.
+- Never reference AI/Claude in commit messages.
+- Stay in your worktree.
+- ALWAYS use the venv python (`ftm-map/scripts/.venv/bin/python3`), never the system python.
+- For query mode, ALWAYS run `setup.sh` first if `.venv` does not exist.
+
+## Requirements
+
+- tool: `ftm-map/scripts/.venv/bin/python3` | required | Python with tree-sitter and SQLite bindings
+- tool: `ftm-map/scripts/setup.sh` | required | virtualenv and dependency installer
+- tool: `ftm-map/scripts/index.py` | required | bootstrap and incremental indexer
+- tool: `ftm-map/scripts/query.py` | required | blast radius, dependency, and FTS5 search queries
+- tool: `ftm-map/scripts/views.py` | required | INTENT.md and .mmd diagram generation from graph
+- tool: `git` | optional | changed file detection for incremental mode
+- config: `~/.claude/ftm-config.yml` | optional | model profile and skills.ftm-map.enabled flag
+
+## Risk
+
+- level: low_write
+- scope: writes and updates .ftm-map/map.db SQLite database; does not modify any project source files; also writes blackboard experience entry
+- rollback: delete .ftm-map/map.db to reset to unindexed state; re-run bootstrap to rebuild
+
+## Approval Gates
+
+- trigger: bootstrap requested on very large codebase (1000+ files) | action: report estimated file count before running, proceed unless user objects
+- complexity_routing: micro → auto | small → auto | medium → auto | large → auto | xl → auto
+
+## Fallbacks
+
+- condition: .venv does not exist | action: run setup.sh first to create it before proceeding
+- condition: tree-sitter binary missing | action: run setup.sh to install dependencies
+- condition: .ftm-map/map.db missing when query requested | action: explain graph not indexed, offer to run bootstrap
+- condition: git not available for incremental changed-file detection | action: fall back to indexing all modified files detected from disk timestamps
+
+## Capabilities
+
+- cli: `ftm-map/scripts/.venv/bin/python3` | required | tree-sitter parsing and SQLite operations
+- cli: `git` | optional | changed file detection for incremental indexing
+
+## Event Payloads
+
+### map_updated
+- skill: string — "ftm-map"
+- project_path: string — absolute path to indexed project
+- symbols_count: number — total symbols in the graph
+- edges_count: number — total dependency edges
+- files_parsed: number — files processed in this operation
+- duration_ms: number — indexing duration
+- mode: string — "bootstrap" | "incremental"
+
+### task_completed
+- skill: string — "ftm-map"
+- operation: string — "bootstrap" | "incremental" | "query"
+- query_type: string | null — "blast-radius" | "deps" | "search" | "info" (for query mode)
+- duration_ms: number — total operation duration

package/ftm-map/scripts/db.py

@@ -0,0 +1,391 @@
+"""
+db.py — SQLite database module for ftm-map.
+
+Manages the symbols/edges/FTS5 schema and provides CRUD operations for the
+code graph. This is a library module — import it from index.py, query.py,
+and views.py.
+
+Schema overview:
+  symbols      — indexed code symbols (functions, classes, methods, etc.)
+  edges        — directed dependency relationships between symbols
+  symbols_fts  — FTS5 virtual table for full-text search (BM25-ranked)
+"""
+
+import hashlib
+import os
+import sqlite3
+from pathlib import Path
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+DB_DIR = ".ftm-map"
+DB_PATH = os.path.join(DB_DIR, "map.db")
+
+# ---------------------------------------------------------------------------
+# Schema DDL
+# ---------------------------------------------------------------------------
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS symbols (
+    id           INTEGER PRIMARY KEY,
+    name         TEXT    NOT NULL,
+    kind         TEXT    NOT NULL,   -- 'function','class','method','variable','import','module'
+    file_path    TEXT    NOT NULL,
+    start_line   INTEGER,
+    end_line     INTEGER,
+    signature    TEXT,
+    doc_comment  TEXT,
+    content_hash TEXT                -- hash of symbol body for change detection
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+    source_id INTEGER NOT NULL REFERENCES symbols(id) ON DELETE CASCADE,
+    target_id INTEGER NOT NULL REFERENCES symbols(id) ON DELETE CASCADE,
+    kind      TEXT    NOT NULL,      -- 'calls','imports','extends','implements','uses'
+    PRIMARY KEY (source_id, target_id, kind)
+);
+
+CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id);
+CREATE INDEX IF NOT EXISTS idx_symbols_file  ON symbols(file_path);
+CREATE INDEX IF NOT EXISTS idx_symbols_name  ON symbols(name);
+
+CREATE VIRTUAL TABLE IF NOT EXISTS symbols_fts USING fts5(
+    name, signature, doc_comment, file_path,
+    content=symbols, content_rowid=id
+);
+"""
+
+# ---------------------------------------------------------------------------
+# Connection management
+# ---------------------------------------------------------------------------
+
+
+def get_connection(project_root: str) -> sqlite3.Connection:
+    """Return a connection to the project's map database.
+
+    Creates .ftm-map/ and initialises the schema if they do not exist yet.
+    WAL mode is enabled for concurrent readers; foreign-key enforcement is on.
+    """
+    db_path = os.path.join(project_root, DB_PATH)
+    os.makedirs(os.path.dirname(db_path), exist_ok=True)
+
+    conn = sqlite3.connect(db_path)
+    conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute("PRAGMA foreign_keys=ON")
+    conn.row_factory = sqlite3.Row
+
+    _init_schema(conn)
+    return conn
+
+
+def _init_schema(conn: sqlite3.Connection) -> None:
+    """Create tables, indexes, and FTS5 virtual table if they do not exist."""
+    conn.executescript(_SCHEMA)
+    conn.commit()
+
+
+# ---------------------------------------------------------------------------
+# Symbol CRUD
+# ---------------------------------------------------------------------------
+
+
+def add_symbol(
+    conn: sqlite3.Connection,
+    name: str,
+    kind: str,
+    file_path: str,
+    start_line: Optional[int],
+    end_line: Optional[int],
+    signature: Optional[str] = None,
+    doc_comment: Optional[str] = None,
+    content_hash: Optional[str] = None,
+) -> int:
+    """Insert a symbol row and keep the FTS5 index in sync.
+
+    Returns the new symbol id.
+    """
+    cursor = conn.execute(
+        """
+        INSERT INTO symbols
+            (name, kind, file_path, start_line, end_line, signature, doc_comment, content_hash)
+        VALUES (?,?,?,?,?,?,?,?)
+        """,
+        (name, kind, file_path, start_line, end_line, signature, doc_comment, content_hash),
+    )
+    symbol_id = cursor.lastrowid
+
+    # FTS5 content= tables require manual insert so BM25 ranking stays accurate.
+    conn.execute(
+        "INSERT INTO symbols_fts(rowid, name, signature, doc_comment, file_path) VALUES (?,?,?,?,?)",
+        (symbol_id, name, signature or "", doc_comment or "", file_path),
+    )
+
+    return symbol_id
+
+
+def remove_symbols_by_file(conn: sqlite3.Connection, file_path: str) -> None:
+    """Delete all symbols (and their edges) for a given file.
+
+    FTS5 rows are removed explicitly before the symbol rows because the
+    content= table does not handle cascaded deletes automatically.
+    ON DELETE CASCADE handles edge cleanup via the symbols foreign key.
+    """
+    ids = [
+        row["id"]
+        for row in conn.execute("SELECT id FROM symbols WHERE file_path=?", (file_path,))
+    ]
+    for sid in ids:
+        conn.execute("DELETE FROM symbols_fts WHERE rowid=?", (sid,))
+
+    conn.execute("DELETE FROM symbols WHERE file_path=?", (file_path,))
+
+
+def get_symbol_by_id(conn: sqlite3.Connection, symbol_id: int) -> Optional[dict]:
+    """Return a symbol row as a dict, or None if not found."""
+    row = conn.execute("SELECT * FROM symbols WHERE id=?", (symbol_id,)).fetchone()
+    return dict(row) if row else None
+
+
+def get_symbol_by_name(conn: sqlite3.Connection, name: str) -> list:
+    """Return all symbols matching *name* (name is not guaranteed unique)."""
+    rows = conn.execute("SELECT * FROM symbols WHERE name=?", (name,)).fetchall()
+    return [dict(r) for r in rows]
+
+
+# ---------------------------------------------------------------------------
+# Edge CRUD
+# ---------------------------------------------------------------------------
+
+
+def add_edge(conn: sqlite3.Connection, source_id: int, target_id: int, kind: str) -> None:
+    """Insert a directed edge. Silently ignored if the edge already exists."""
+    conn.execute(
+        "INSERT OR IGNORE INTO edges (source_id, target_id, kind) VALUES (?,?,?)",
+        (source_id, target_id, kind),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Graph traversal — recursive CTEs
+# ---------------------------------------------------------------------------
+
+
+def get_transitive_deps(
+    conn: sqlite3.Connection, symbol_id: int, max_depth: int = 10
+) -> list:
+    """Return all symbols this symbol transitively depends on (forward closure).
+
+    Cycle prevention is handled by tracking visited ids as a comma-separated
+    path string inside the CTE; a node is skipped if its id already appears in
+    the path string.
+
+    Results are ordered by traversal depth (shallowest first) and deduplicated.
+    """
+    query = """
+    WITH RECURSIVE dep_chain(id, name, kind, file_path, depth, path) AS (
+        -- Base: direct dependencies of the seed symbol
+        SELECT s.id,
+               s.name,
+               s.kind,
+               s.file_path,
+               0,
+               CAST(s.id AS TEXT)
+        FROM   edges e
+        JOIN   symbols s ON s.id = e.target_id
+        WHERE  e.source_id = ?
+
+        UNION ALL
+
+        -- Recursive: dependencies of already-visited nodes
+        SELECT s.id,
+               s.name,
+               s.kind,
+               s.file_path,
+               dc.depth + 1,
+               dc.path || ',' || CAST(s.id AS TEXT)
+        FROM   dep_chain dc
+        JOIN   edges e   ON e.source_id = dc.id
+        JOIN   symbols s ON s.id = e.target_id
+        WHERE  dc.depth < ?
+        AND    INSTR(dc.path, CAST(s.id AS TEXT)) = 0  -- cycle guard
+    )
+    SELECT DISTINCT id, name, kind, file_path, depth
+    FROM   dep_chain
+    ORDER  BY depth
+    """
+    rows = conn.execute(query, (symbol_id, max_depth)).fetchall()
+    return [dict(r) for r in rows]
+
+
+def get_reverse_deps(
+    conn: sqlite3.Connection, symbol_id: int, max_depth: int = 10
+) -> list:
+    """Return all symbols that transitively depend on this symbol (blast radius).
+
+    Traverses edges in reverse (callers/importers of the seed symbol).
+    Same cycle-prevention strategy as get_transitive_deps.
+    """
+    query = """
+    WITH RECURSIVE rev_chain(id, name, kind, file_path, depth, path) AS (
+        -- Base: direct dependents of the seed symbol
+        SELECT s.id,
+               s.name,
+               s.kind,
+               s.file_path,
+               0,
+               CAST(s.id AS TEXT)
+        FROM   edges e
+        JOIN   symbols s ON s.id = e.source_id
+        WHERE  e.target_id = ?
+
+        UNION ALL
+
+        -- Recursive: dependents of already-visited nodes
+        SELECT s.id,
+               s.name,
+               s.kind,
+               s.file_path,
+               rc.depth + 1,
+               rc.path || ',' || CAST(s.id AS TEXT)
+        FROM   rev_chain rc
+        JOIN   edges e   ON e.target_id = rc.id
+        JOIN   symbols s ON s.id = e.source_id
+        WHERE  rc.depth < ?
+        AND    INSTR(rc.path, CAST(s.id AS TEXT)) = 0  -- cycle guard
+    )
+    SELECT DISTINCT id, name, kind, file_path, depth
+    FROM   rev_chain
+    ORDER  BY depth
+    """
+    rows = conn.execute(query, (symbol_id, max_depth)).fetchall()
+    return [dict(r) for r in rows]
+
+
+# ---------------------------------------------------------------------------
+# Full-text search
+# ---------------------------------------------------------------------------
+
+
+def fts_search(conn: sqlite3.Connection, query_text: str, limit: int = 10) -> list:
+    """BM25-ranked full-text search over symbol names, signatures, and doc comments.
+
+    Returns up to *limit* symbol dicts with an additional 'rank' field.
+    Lower rank values indicate better matches (BM25 scores are negative in
+    SQLite's fts5 implementation).
+    """
+    query = """
+    SELECT s.*, fts.rank
+    FROM   symbols_fts fts
+    JOIN   symbols s ON s.id = fts.rowid
+    WHERE  symbols_fts MATCH ?
+    ORDER  BY fts.rank
+    LIMIT  ?
+    """
+    rows = conn.execute(query, (query_text, limit)).fetchall()
+    return [dict(r) for r in rows]
+
+
+# ---------------------------------------------------------------------------
+# Statistics
+# ---------------------------------------------------------------------------
+
+
+def get_stats(conn: sqlite3.Connection) -> dict:
+    """Return high-level database statistics."""
+    symbols_count = conn.execute("SELECT COUNT(*) FROM symbols").fetchone()[0]
+    edges_count = conn.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
+    files_count = conn.execute(
+        "SELECT COUNT(DISTINCT file_path) FROM symbols"
+    ).fetchone()[0]
+    return {
+        "symbols": symbols_count,
+        "edges": edges_count,
+        "files": files_count,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Utility helpers
+# ---------------------------------------------------------------------------
+
+
+def hash_content(content: str) -> str:
+    """Return a SHA-256 hex digest for *content*. Useful for change detection."""
+    return hashlib.sha256(content.encode("utf-8")).hexdigest()
+
+
+# ---------------------------------------------------------------------------
+# Smoke-test entrypoint
+# ---------------------------------------------------------------------------
+
+if __name__ == "__main__":
+    import tempfile
+
+    print("Running db.py smoke tests …")
+
+    with tempfile.TemporaryDirectory() as tmp:
+        conn = get_connection(tmp)
+
+        # ---- symbols ----
+        sid_a = add_symbol(
+            conn, "parse_file", "function", "src/parser.py", 10, 40,
+            signature="def parse_file(path: str) -> AST",
+            doc_comment="Parse a source file and return its AST.",
+            content_hash=hash_content("def parse_file(): pass"),
+        )
+        sid_b = add_symbol(
+            conn, "tokenize", "function", "src/lexer.py", 1, 20,
+            signature="def tokenize(src: str) -> list",
+        )
+        sid_c = add_symbol(
+            conn, "build_index", "function", "src/index.py", 5, 60,
+            signature="def build_index(root: str) -> None",
+            doc_comment="Build the code graph index for a project.",
+        )
+
+        assert get_symbol_by_id(conn, sid_a)["name"] == "parse_file", "get_symbol_by_id failed"
+        assert len(get_symbol_by_name(conn, "tokenize")) == 1, "get_symbol_by_name failed"
+
+        # ---- edges ----
+        # build_index → parse_file → tokenize
+        add_edge(conn, sid_c, sid_a, "calls")
+        add_edge(conn, sid_a, sid_b, "calls")
+        add_edge(conn, sid_c, sid_a, "calls")  # duplicate — should be ignored
+
+        conn.commit()
+
+        # ---- transitive deps ----
+        deps = get_transitive_deps(conn, sid_c)
+        dep_ids = {d["id"] for d in deps}
+        assert sid_a in dep_ids and sid_b in dep_ids, f"transitive deps wrong: {dep_ids}"
+
+        # ---- reverse deps ----
+        rdeps = get_reverse_deps(conn, sid_b)
+        rdep_ids = {d["id"] for d in rdeps}
+        assert sid_a in rdep_ids and sid_c in rdep_ids, f"reverse deps wrong: {rdep_ids}"
+
+        # ---- FTS search ----
+        results = fts_search(conn, "parse")
+        assert any(r["name"] == "parse_file" for r in results), "FTS search failed"
+
+        results_doc = fts_search(conn, "index")
+        assert any(r["name"] == "build_index" for r in results_doc), "FTS doc_comment search failed"
+
+        # ---- remove by file ----
+        remove_symbols_by_file(conn, "src/lexer.py")
+        conn.commit()
+        assert get_symbol_by_id(conn, sid_b) is None, "remove_symbols_by_file failed"
+
+        # ---- stats ----
+        stats = get_stats(conn)
+        assert stats["symbols"] == 2, f"expected 2 symbols after removal, got {stats['symbols']}"
+        assert stats["files"] == 2, f"expected 2 files, got {stats['files']}"
+        # edge from parse_file → tokenize should be gone via CASCADE
+        edge_count = conn.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
+        assert edge_count == 1, f"expected 1 edge after file removal, got {edge_count}"
+
+        print("All smoke tests passed.")
+        print(f"Stats: {get_stats(conn)}")