seam-code 0.3.0__tar.gz

seam_code-0.3.0/.env.example

@@ -0,0 +1,13 @@
+# Seam configuration — copy to .env, never commit .env
+# All values shown are defaults. Seam works with zero config.
+
+SEAM_LOG_LEVEL=INFO
+
+# Override where the index database is stored (default: .seam/seam.db)
+# SEAM_DB_PATH=.seam/seam.db
+
+# File watcher debounce delay in milliseconds (default: 500)
+# SEAM_WATCHER_DEBOUNCE_MS=500
+
+# Maximum file size to index in bytes (default: 1MB)
+# SEAM_MAX_FILE_BYTES=1048576

seam_code-0.3.0/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.eggs/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Testing / coverage
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Environment
+.env
+
+# Seam index (local per-project, not committed by default)
+.seam/
+
+# Built SPA — produced by `make build-web` / `cd web && npm run build`.
+# Shipped inside the wheel via hatch artifacts config; not committed to git.
+seam/_web/
+
+# GitNexus index
+.gitnexus/
+
+# Competitor index artifacts (benchmark only — never committed)
+.codegraph/
+graphify-out/
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Distribution
+*.tar.gz
+*.zip
+
+# uv lockfile (commit uv.lock in production, optional here)
+# uv.lock
+
+.bach/
+.claude/
+.koda/
+
+# QA artifacts (gstack /qa reports + screenshots) — local, not committed
+.gstack/

seam_code-0.3.0/AGENTS.md

@@ -0,0 +1,101 @@
+<!-- gitnexus:start -->
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **seam** (273 symbols, 293 relationships, 0 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
+
+## When Debugging
+
+1. `gitnexus_query({query: "<error or symptom>"})` — find execution flows related to the issue
+2. `gitnexus_context({name: "<suspect function>"})` — see all callers, callees, and process participation
+3. `READ gitnexus://repo/seam/process/{processName}` — trace the full execution flow step by step
+4. For regressions: `gitnexus_detect_changes({scope: "compare", base_ref: "main"})` — see what your branch changed
+
+## When Refactoring
+
+- **Renaming**: MUST use `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` first. Review the preview — graph edits are safe, text_search edits need manual review. Then run with `dry_run: false`.
+- **Extracting/Splitting**: MUST run `gitnexus_context({name: "target"})` to see all incoming/outgoing refs, then `gitnexus_impact({target: "target", direction: "upstream"})` to find all external callers before moving code.
+- After any refactor: run `gitnexus_detect_changes({scope: "all"})` to verify only expected files changed.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
+- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
+
+## Tools Quick Reference
+
+| Tool | When to use | Command |
+|------|-------------|---------|
+| `query` | Find code by concept | `gitnexus_query({query: "auth validation"})` |
+| `context` | 360-degree view of one symbol | `gitnexus_context({name: "validateUser"})` |
+| `impact` | Blast radius before editing | `gitnexus_impact({target: "X", direction: "upstream"})` |
+| `detect_changes` | Pre-commit scope check | `gitnexus_detect_changes({scope: "staged"})` |
+| `rename` | Safe multi-file rename | `gitnexus_rename({symbol_name: "old", new_name: "new", dry_run: true})` |
+| `cypher` | Custom graph queries | `gitnexus_cypher({query: "MATCH ..."})` |
+
+## Impact Risk Levels
+
+| Depth | Meaning | Action |
+|-------|---------|--------|
+| d=1 | WILL BREAK — direct callers/importers | MUST update these |
+| d=2 | LIKELY AFFECTED — indirect deps | Should test |
+| d=3 | MAY NEED TESTING — transitive | Test if critical path |
+
+## Resources
+
+| Resource | Use for |
+|----------|---------|
+| `gitnexus://repo/seam/context` | Codebase overview, check index freshness |
+| `gitnexus://repo/seam/clusters` | All functional areas |
+| `gitnexus://repo/seam/processes` | All execution flows |
+| `gitnexus://repo/seam/process/{name}` | Step-by-step execution trace |
+
+## Self-Check Before Finishing
+
+Before completing any code modification task, verify:
+1. `gitnexus_impact` was run for all modified symbols
+2. No HIGH/CRITICAL risk warnings were ignored
+3. `gitnexus_detect_changes()` confirms changes match expected scope
+4. All d=1 (WILL BREAK) dependents were updated
+
+## Keeping the Index Fresh
+
+After committing code changes, the GitNexus index becomes stale. Re-run analyze to update it:
+
+```bash
+npx gitnexus analyze
+```
+
+If the index previously included embeddings, preserve them by adding `--embeddings`:
+
+```bash
+npx gitnexus analyze --embeddings
+```
+
+To check whether embeddings exist, inspect `.gitnexus/meta.json` — the `stats.embeddings` field shows the count (0 means no embeddings). **Running analyze without `--embeddings` will delete any previously generated embeddings.**
+
+> Claude Code users: A PostToolUse hook handles this automatically after `git commit` and `git merge`.
+
+## CLI
+
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
+| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
+| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
+| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
+| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
+| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
+
+<!-- gitnexus:end -->

seam_code-0.3.0/APP_FLOW.md

@@ -0,0 +1,151 @@
+# App Flow — Seam (Phase 0)
+
+> Agent interaction flows. Written from the AI agent's perspective.
+
+---
+
+## Flow 1: First-Time Setup (Developer)
+
+```
+Developer opens a new project
+    │
+    ▼
+$ seam init
+    │
+    ├── Walks directory tree
+    ├── Detects language per file (Python, TypeScript/JavaScript)
+    ├── Parses each file with tree-sitter
+    ├── Extracts: symbols (functions, classes, methods), edges (imports, calls)
+    ├── Writes to .seam/seam.db (SQLite + FTS5)
+    └── Prints summary: "Indexed 847 files, 12,304 symbols in 8.3s"
+    │
+    ▼
+$ seam start
+    │
+    ├── Starts file watcher (background daemon)
+    ├── Starts MCP server (stdio transport)
+    └── MCP tools ready: seam_query, seam_context, seam_search
+```
+
+**Developer then adds to their Claude Code MCP config:**
+```json
+{
+  "mcpServers": {
+    "seam": {
+      "command": "seam",
+      "args": ["start", "--stdio"],
+      "cwd": "/path/to/project"
+    }
+  }
+}
+```
+
+---
+
+## Flow 2: Session Start (Agent)
+
+```
+Agent receives task: "Add rate limiting to the API"
+    │
+    ▼
+Agent uses seam_query("rate limiting middleware")
+    │
+    ├── FTS5 search: finds symbols named 'RateLimiter', 'throttle', etc.
+    ├── Graph search: finds symbols in same cluster as 'middleware'
+    └── Returns: [{symbol, file, line, snippet, callers_count, callees_count}]
+    │
+    ▼
+Agent narrows to relevant symbol with seam_context("APIMiddleware")
+    │
+    ├── Returns: callers (what calls this), callees (what this calls)
+    ├── File location + line number
+    └── Docstring / comment if present
+    │
+    ▼
+Agent has full picture before reading a single file
+    Ready to implement without exploration tax
+```
+
+---
+
+## Flow 3: File Change (Auto-Sync)
+
+```
+Developer saves auth/middleware.py
+    │
+    ▼
+File watcher detects change (FSEvents/inotify)
+    │
+    ▼
+Debounce 500ms (coalesce rapid saves)
+    │
+    ▼
+Re-parse changed file with tree-sitter
+    │
+    ├── Diff: which symbols added / removed / changed?
+    ├── Update seam.db (delete old, insert new)
+    └── Update FTS5 index for changed symbols
+    │
+    ▼
+Index fresh — next seam_query returns updated results
+```
+
+---
+
+## Flow 4: Finding a Symbol (Agent)
+
+```
+Agent wants to understand how authentication works
+    │
+    ▼
+seam_search("authenticate login token")
+    │
+    └── Returns: top-10 FTS5 matches with snippets
+              [{symbol: "authenticate_user", file: "auth/service.py:47", snippet: "..."}]
+    │
+    ▼
+seam_context("authenticate_user")
+    │
+    └── Returns:
+          {
+            "symbol": "authenticate_user",
+            "file": "auth/service.py",
+            "line": 47,
+            "docstring": "Validates credentials and returns JWT token",
+            "callers": ["LoginHandler.post", "TestAuth.test_valid_login"],
+            "callees": ["hash_password", "create_token", "UserRepository.find_by_email"]
+          }
+    │
+    ▼
+Agent knows: WHERE it is, WHO calls it, WHAT it calls
+No file reads needed to get this structural picture
+```
+
+---
+
+## Flow 5: Status Check
+
+```
+$ seam status
+    │
+    └── Prints:
+          Project: /Users/jordi/projects/bach
+          Database: .seam/seam.db (14.2 MB)
+          Indexed: 2026-06-01 14:23:01 (3 minutes ago)
+          Files: 1,247 | Symbols: 18,432 | Edges: 41,209
+          Languages: Python (892 files), TypeScript (355 files)
+          Watcher: running (PID 84201)
+          Status: FRESH
+```
+
+---
+
+## Error States
+
+| State | User sees | What happens |
+|---|---|---|
+| Unsupported file type | Silently skipped | Added to .seam/ignored.log |
+| Parse error (malformed file) | Warning in seam status | Skipped, rest of index proceeds |
+| seam.db locked (concurrent write) | Retry with backoff | Automatic, transparent |
+| File watcher loses connection | Warning + restart | Auto-restart with exponential backoff |
+| Symbol not found | `{"results": [], "message": "No results for 'X'"}` | Empty results, not an error |

seam_code-0.3.0/BACKEND_STRUCTURE.md

@@ -0,0 +1,253 @@
+# Backend Structure — Seam
+
+> This is the authoritative module map. Every new file must fit this structure.
+> Seam has no frontend. All code is in the `seam/` Python package.
+
+---
+
+## Package Layout
+
+```
+seam/                           ← Python package root
+├── __init__.py                 ← Version + public API surface
+├── config.py                   ← All settings (from env via os.getenv)
+│                                 SEAM_LANGUAGE_MAP: .py→python, .ts/.tsx→typescript,
+│                                 .js/.mjs/.cjs→javascript, .go→go, .rs→rust
+│
+├── cli/                        ← CLI entry points (Typer)
+│   ├── __init__.py
+│   └── main.py                 ← app = typer.Typer(); init, start, status
+│
+├── analysis/                   ← Read-only graph reasoning + community detection
+│   ├── __init__.py
+│   ├── clustering.py           ← LEAF: pure-Python Louvain community detection
+│   │                             detect_communities(nodes, edges) → {name: cluster_id}
+│   │                             No SQLite, no I/O, no config. Deterministic.
+│   └── cluster_naming.py       ← LEAF: cluster label generation
+│                                 deterministic_label(members) → str (always available)
+│                                 label_cluster(members, naming_mode, ...) → (label, source)
+│                                 Opt-in LLM path via stdlib urllib only. Never raises.
+│
+├── indexer/                    ← Parse → extract → store pipeline
+│   ├── __init__.py
+│   ├── parser.py               ← tree-sitter parsing per language
+│   │                             parse_python, parse_typescript, parse_javascript,
+│   │                             parse_go, parse_rust — all delegate to _parse()
+│   ├── graph_common.py         ← LEAF: shared TypedDicts, constants, helpers
+│   │                             Symbol, Edge, Comment, Confidence; _text, _node_name,
+│   │                             _make_symbol, _match_marker, _block_comment_lines,
+│   │                             _find_enclosing_function, _go_recv_type_name,
+│   │                             _rust_impl_type_name. Imports stdlib + tree_sitter only.
+│   ├── graph_go_rust.py        ← Go + Rust extractors (imports graph_common only)
+│   │                             _extract_symbols_go/rust, _extract_edges_go/rust,
+│   │                             _extract_comments_go/rust, doc-comment helpers
+│   ├── graph.py                ← Python + TypeScript dispatchers; re-exports public types
+│   │                             from graph_common; imports Go/Rust extractors from
+│   │                             graph_go_rust. Public API: extract_symbols, extract_edges,
+│   │                             extract_comments.
+│   ├── pipeline.py             ← Shared parse→extract→upsert path (CLI + watcher)
+│   ├── cluster_index.py        ← Clustering orchestration (indexer layer bridge)
+│   │                             index_clusters(conn, ...) → int (cluster count or -1)
+│   │                             Reads DB → detect_communities → label_cluster → writes
+│   │                             clusters table + symbols.cluster_id in one transaction.
+│   │                             Called by seam init only; watcher never calls this.
+│   └── db.py                   ← SQLite write operations (schema + upsert)
+│
+├── watcher/                    ← OS file watcher
+│   ├── __init__.py
+│   └── daemon.py               ← watchdog EventHandler; debounced re-index
+│
+├── server/                     ← MCP server
+│   ├── __init__.py
+│   ├── mcp.py                  ← MCP server setup (stdio transport)
+│   └── tools.py                ← seam_query, seam_context, seam_search implementations
+│
+└── query/                      ← Query engine (read path)
+    ├── __init__.py
+    ├── engine.py               ← FTS5 + graph traversal queries; context() enriched
+    │                             with cluster_id, cluster_label, cluster_peers (Phase 2)
+    └── clusters.py             ← Read-only cluster queries (Phase 2)
+                                  list_clusters(conn) → [{id, label, size}]
+                                  cluster_members(conn, id) → [{name, file, line, kind}]
+                                  cluster_peers(conn, symbol) → (id, label, peers) | None
+                                  Guards pre-v4 indexes (returns empty + one-time warning).
+```
+
+---
+
+## Layer Rules (Import Hierarchy)
+
+```
+cli/ → server/ → analysis/ → query/ → indexer/db
+  ↓                                         ↑
+  └─→ indexer/cluster_index → analysis/clustering + analysis/cluster_naming
+                                      ↑
+                            watcher/ → indexer/
+```
+
+Within `indexer/`, the import order is strictly:
+```
+graph_common  (leaf — stdlib + tree_sitter only)
+     ↑              ↑
+graph_go_rust    graph.py   (both import from graph_common; graph.py also imports graph_go_rust)
+     ↑
+graph.py (dispatchers + re-exports)
+     ↑
+pipeline.py
+
+analysis/clustering      (leaf — stdlib only, no seam imports)
+analysis/cluster_naming  (leaf — stdlib only, no seam imports)
+     ↑
+indexer/cluster_index    (bridge: imports analysis + db)
+```
+
+| Layer | Can import from | Cannot import from |
+|---|---|---|
+| `cli/` | server, analysis, indexer, watcher, config | — |
+| `server/` | analysis, query, config | cli, watcher |
+| `analysis/` (non-clustering) | indexer.db, query, config | cli, server |
+| `analysis/clustering` | stdlib only | any seam module (leaf) |
+| `analysis/cluster_naming` | stdlib only | any seam module (leaf) |
+| `indexer/cluster_index` | analysis.clustering, analysis.cluster_naming, indexer.db, config | cli, server, query, watcher |
+| `query/` | indexer.db, config | cli, server, analysis, watcher |
+| `indexer/pipeline` | indexer.db, indexer.graph, indexer.parser, config | cli, server, query, analysis, watcher |
+| `indexer/graph` | graph_common, graph_go_rust, config | cli, server, query, analysis, watcher |
+| `indexer/graph_go_rust` | graph_common only | graph.py or any other seam module |
+| `indexer/graph_common` | stdlib, tree_sitter only | any seam module (leaf) |
+| `indexer/parser` | config, tree_sitter grammars | any seam indexer sub-module |
+| `indexer/db` | config | cli, server, query, analysis, watcher |
+| `watcher/` | indexer, config | cli, server, query, analysis |
+| `config` | stdlib only | anything in seam/ |
+
+---
+
+## Module Responsibilities
+
+### `seam/config.py`
+- Reads all config from `os.getenv()` with defaults
+- Exports: `SEAM_DB_PATH`, `SEAM_LOG_LEVEL`, `SEAM_DEBOUNCE_MS`, `SEAM_MAX_FILE_BYTES`,
+  `SEAM_CLUSTER_NAMING`, `SEAM_LLM_API_KEY`, `SEAM_LLM_MODEL`, `SEAM_CLUSTER_MIN_SIZE`
+- Never import from other seam modules (avoids circular imports)
+
+### `seam/analysis/clustering.py` (leaf — Phase 2)
+- `detect_communities(nodes, edges) → dict[str, int]` — pure Louvain community detection
+- No SQLite, no file I/O, no config. Input: node names + edge pairs. Output: {name: cluster_id}.
+- Deterministic: nodes processed in sorted order, tie-breaking by community label.
+- Never raises: falls back to singleton clusters on any internal error.
+
+### `seam/analysis/cluster_naming.py` (leaf — Phase 2)
+- `deterministic_label(members) → str` — derive label from dominant dir + highest-degree symbol
+- `label_cluster(members, naming_mode, api_key, model) → (label, naming_source)` — dispatch
+- Opt-in LLM path (`_call_llm_for_label`) uses stdlib urllib only, is isolated, and is
+  never called unless `naming_mode="llm"` AND `api_key` is set.
+- Any LLM error falls back to deterministic silently — never raises.
+
+### `seam/indexer/cluster_index.py` (Phase 2)
+- `index_clusters(conn, naming_mode, llm_api_key, llm_model, min_size) → int`
+  — orchestrates: read symbols+edges → detect_communities → label_cluster → write DB
+- Returns cluster count (≥0) or -1 on error (never raises).
+- Called by `seam init` ONLY, never by the watcher.
+- Clears old cluster state first (even before early returns) to avoid ghost clusters.
+
+### `seam/indexer/parser.py`
+- One function per language: `parse_python`, `parse_typescript`, `parse_javascript`,
+  `parse_go`, `parse_rust` — all delegate to the internal `_parse(path, language)` helper.
+- Returns raw tree-sitter root Node for graph.py to interpret.
+- Handles encoding, binary files, and parse errors gracefully. Never raises.
+
+### `seam/indexer/graph_common.py` (leaf — Phase 1b addition)
+- Shared TypedDicts: `Symbol`, `Edge`, `Comment`; type alias: `Confidence`
+- Shared constants: `SEMANTIC_MARKERS`, `_MARKER_RE`
+- Shared helpers: `_text`, `_node_name`, `_make_symbol`, `_match_marker`,
+  `_block_comment_lines`, `_arrow_function_name`, `_find_enclosing_function`
+- Go/Rust receiver helpers: `_go_recv_type_name`, `_rust_impl_type_name`
+  (kept here so `_find_enclosing_function` can call them without importing from
+  graph_go_rust — this is what maintains the leaf property)
+- MUST remain a leaf: imports stdlib and tree_sitter only.
+
+### `seam/indexer/graph_go_rust.py` (Phase 1b addition)
+- Go extractors: `_extract_symbols_go`, `_extract_edges_go`, `_extract_comments_go`
+- Rust extractors: `_extract_symbols_rust`, `_extract_edges_rust`, `_extract_comments_rust`
+- Doc-comment helpers: `_go_doc_comment`, `_rust_doc_comment`
+- Imports from `graph_common` only — never from `graph.py`.
+
+### `seam/indexer/graph.py`
+- Public API: `extract_symbols(node, language, filepath) → list[Symbol]`
+- Public API: `extract_edges(node, language, filepath, symbols) → list[Edge]`
+- Public API: `extract_comments(node, language, filepath) → list[Comment]`
+- Python + TypeScript/JavaScript extractors live here.
+- Go + Rust extractors are delegated to graph_go_rust.py (imported at top level).
+- Re-exports `Symbol`, `Edge`, `Comment`, `Confidence` from graph_common so callers
+  using `from seam.indexer.graph import Symbol` continue to work unchanged.
+- Symbol: `{name, kind, file, start_line, end_line, docstring}`
+- Edge: `{source, target, kind, file, line, confidence}`
+
+### `seam/indexer/db.py`
+- `init_db(db_path) → Connection` — create schema if not exists
+- `upsert_file(conn, filepath, symbols, edges)` — atomic file update
+- `delete_file(conn, filepath)` — remove all data for a file
+- Never holds long-lived connections; pass conn as parameter
+
+### `seam/query/engine.py`
+- `query(conn, concept, limit) → list[QueryResult]` — FTS5 + graph hybrid
+- `context(conn, symbol_name) → ContextResult` — callers + callees + metadata +
+  cluster_id, cluster_label, cluster_peers (Phase 2 enrichment via query/clusters.py)
+- `search(conn, text, limit) → list[SearchResult]` — FTS5 full-text
+
+### `seam/query/clusters.py` (Phase 2)
+- `list_clusters(conn) → list[ClusterRow]` — all clusters sorted by id
+- `cluster_members(conn, cluster_id) → list[MemberRow]` — symbols in one cluster
+- `cluster_peers(conn, symbol) → (cluster_id, label, peers) | None` — cluster context
+- Guards pre-v4 indexes (no table/column): returns empty results + one-time warning.
+  Mirrors the `_comments_table_exists` guard in `query/comments.py`.
+
+### `seam/server/tools.py`
+- Thin adapter: MCP tool handlers that call query.engine functions
+- Input validation only — no business logic
+- Returns MCP-compatible response format
+
+### `seam/watcher/daemon.py`
+- `SeamWatcher(db_path, root_path)` — watchdog EventHandler subclass
+- `on_modified(event)` — debounced re-index of changed file
+- `start()` / `stop()` — manage Observer lifecycle
+
+---
+
+## File Naming Conventions
+
+| Type | Convention | Example |
+|---|---|---|
+| Python files | snake_case | `user_service.py` |
+| Python classes | PascalCase | `SeamWatcher` |
+| Python functions | snake_case | `extract_symbols()` |
+| Python constants | UPPER_SNAKE_CASE | `SEAM_DB_PATH` |
+| Test files | `test_<module>.py` | `test_parser.py` |
+| Test classes | `Test<Feature>` | `TestPythonParser` |
+
+---
+
+## Tests Layout
+
+```
+tests/
+├── unit/                       ← Pure function tests; no I/O
+│   ├── test_parser.py          ← parse_python, parse_typescript
+│   ├── test_graph.py           ← extract_symbols, extract_edges
+│   └── test_query_engine.py    ← query, context, search (in-memory SQLite)
+│
+├── integration/                ← Tests that hit real SQLite + file system
+│   ├── test_indexer.py         ← Full index pipeline
+│   └── test_watcher.py         ← Watcher → re-index cycle
+│
+└── fixtures/                   ← Sample source files for parser tests
+    ├── sample.py               ← Python with functions, classes, imports
+    └── sample.ts               ← TypeScript with functions, interfaces
+```
+
+---
+
+## Max Size Rules
+
+- Max 200 lines per function (from global CLAUDE.md)
+- Max 1000 lines per file (from global CLAUDE.md)
+- If a module exceeds 1000 lines, split into `_module_part_a.py` + `_module_part_b.py` and re-export from `module.py`