Metadata-Version: 2.4
Name: synapse-pkg
Version: 3.0.0
Summary: Synapse: Repository Intelligence Engine — local-first structural analysis and retrieval for code repositories
Author: Piyush Garg
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tree-sitter<0.27,>=0.23
Requires-Dist: tree-sitter-python<0.26,>=0.23
Requires-Dist: tree-sitter-javascript<0.26,>=0.23
Requires-Dist: tree-sitter-typescript<0.24,>=0.23
Dynamic: license-file

# Synapse: Repository Intelligence Engine

Synapse is a local-first Repository Intelligence Engine that constructs and maintains a persistent, structured representation of a software codebase. It analyzes source files using Tree-sitter, builds a queryable knowledge graph, tracks code changes incrementally across Git commits, and provides deterministic structural retrieval and context synthesis for developers and external AI tools.

---

## 1. Installation

### Requirements
- **Python**: `>= 3.10` (tested on Python 3.10, 3.11, 3.12, 3.13 on Windows and Linux)
- **Git**: `git` executable available in `PATH`

### Standard Installation
Clone this repository and install into your active Python environment:

```bash
git clone https://github.com/your-org/synapse.git
cd synapse
pip install .
```

To install in development/testing mode with dependencies:
```bash
pip install -e .
pip install pytest
```

---

## 2. Quickstart

Run Synapse in any Git repository:

```bash
# 1. Initialize Synapse tracking in the current repository
synapse init

# 2. Build the initial structural index
synapse index

# 3. View index health and repository status
synapse status

# 4. Search for symbols or files
synapse search UserService

# 5. Inspect a symbol, its hierarchy, and callers
synapse inspect UserService

# 6. Generate focused context for LLMs or review
synapse context get_user

# 7. Export the complete index
synapse export json -o index.json
synapse export md -o index.md
synapse export zip -o snapshot.zip
```

---

## 3. Command Reference & Real Outputs

### `synapse init`
Initializes `.synapse/` in the repository root and sets up the SQLite storage schema. Safe and idempotent to re-run on an existing repository without overwriting indexed data.

```bash
$ synapse init
Synapse initialized successfully (schema v1).
```

### `synapse index [--rebuild] [--json]`
Scans tracked source files and updates the database.
- **Initial run**: Scans all eligible supported files at `HEAD` and saves a checkpoint.
- **Subsequent runs**: Computes `git diff` against the last checkpoint and updates only added, modified, deleted, or renamed files.
- `--rebuild`: Forces a complete rebuild from scratch, wiping stale records.
- `--json`: Emits raw indexing statistics as JSON.

```bash
$ synapse index
Indexed 6 files, 9 symbols.
  Files processed: 6
  Symbols found: 9
```

When run after commits modifying source code:
```bash
$ synapse index
Incremental update: 5 files changed.
  Added: 1, Modified: 2, Deleted: 1, Renamed: 1
```

When run with no changes:
```bash
$ synapse index
Repository unchanged since checkpoint cc17d9d8. Nothing to index.
```

### `synapse status [--json]`
Displays index state, commit checkpoint, error counts, and working tree cleanliness.

```bash
$ synapse status
Synapse Status:
  HEAD commit:    acab2080
  Last indexed:   acab2080
  Up to date:     yes
  Files indexed:  6
  Symbols:        11
  Edges:          27
```

If the working tree has uncommitted modifications:
```bash
$ synapse status
Synapse Status:
  HEAD commit:    acab2080
  Last indexed:   acab2080
  Up to date:     no (working tree dirty)
  Warning: Working tree has uncommitted changes not reflected in the index.
```

### `synapse search <query> [--limit N] [--json]`
Searches symbols (by name and qualified name) and files. Results are ranked by match precision (exact match > prefix match > substring match).

```bash
$ synapse search UserService
Found 2 result(s) for 'UserService':
  class     UserService  (backend/services/user_service.py:3)
  method    UserService.get_user  (backend/services/user_service.py:4)
```

### `synapse inspect <symbol> [--depth N] [--json]`
Inspects a specific symbol's definition, enclosing scope, base classes, subclasses, resolved callers/callees, imports, and unresolved references. Traverses relationships up to `--depth` hops (default: 1).

```bash
$ synapse inspect UserService
Symbol: UserService (class)
  File:     backend/services/user_service.py:3-5
  ID:       57992df372a7a124
  Inherits from:
    - BaseService (backend/base.py:1)
```

If multiple symbols match the query, Synapse reports ambiguity and presents candidate options with locations rather than guessing:
```bash
$ synapse inspect execute
Ambiguous symbol query 'execute'. Multiple symbols match:
  - execute (method) in backend/base.py:3
  - execute (method) in backend/services/worker.py:12
Specify the fully qualified name or refine query.
```

### `synapse context <query> [--max-results N] [--max-bytes N] [--depth N] [-o OUTPUT] [--json]`
Generates a structured, bounded context document around a symbol or query. Includes actual source snippets with line numbers, relationship graph neighbors up to `--depth`, and explicit listings of unresolved dependencies. Detects if disk source files are stale relative to `HEAD`.

```bash
$ synapse context get_user
# Synapse Repository Context: get_user

Note: This context document was generated deterministically from static analysis. Snippets reflect indexed files. Dynamic calls, runtime reflection, and unindexed files remain unresolved and must not be assumed to be fully understood.

Found 1 item(s):

## Method: UserService.get_user
Path: `backend/services/user_service.py` (Lines 4-5)
Reason: exact match
```
    def get_user(self, user_id: int):
        return self.execute()
```
Calls:
  - BaseService.execute (backend/base.py:4)
```

### `synapse export <json|md|zip> [-o OUTPUT]`
Exports canonical index data into portable formats.
- **json**: Full schema-versioned JSON dump containing files, symbols, references, and edges.
- **md**: Deterministic Markdown reference document detailing repository architecture.
- **zip**: Self-contained archive package containing `index.json`, `index.md`, and `README.txt` with deterministic timestamps.

```bash
$ synapse export json -o synapse_export.json
Exported JSON index to synapse_export.json

$ synapse export md -o synapse_export.md
Exported Markdown overview to synapse_export.md

$ synapse export zip -o synapse_export.zip
Exported ZIP snapshot to synapse_export.zip
```

---

## 4. Index Semantics & Architecture

```
Git Repository (HEAD)
       │
  Git Diff (-M -z) ─── Incremental Change Detection
       │
  Tree-sitter ──────── Language Parsers (Python, JS, TS, TSX)
       │
  AST Analyzers ────── Structural Extraction (Symbols, Imports, Inheritance, Calls)
       │
  SQLite Index ─────── Persistent Storage (.synapse/index.db)
       │
  Graph Builder ────── Edge Generation & Cross-File Reference Resolution
       │
  Retrieval Engine ─── Search, Inspect, Context & Deterministic Exports
```

- **Source of Truth**: The Git commit tree at `HEAD` is the authoritative source of truth.
- **Committed State vs Working Tree**: Synapse indexes committed repository states. `synapse status` informs the user if the local working tree has uncommitted edits.
- **Transactional Updates**: All index writes, deletes, and checkpoint updates occur within atomic SQLite transactions. If a parsing or indexing error occurs mid-run, changes roll back and the checkpoint is not advanced.
- **Zero Modification Guarantee**: Synapse NEVER writes to, modifies, or deletes user source files. All internal metadata resides strictly in `.synapse/index.db`.

---

## 5. Exclusions & Safety

Synapse automatically excludes paths matching standard ignored patterns:
- Version control metadata: `.git`, `.gitignore`
- Synapse metadata: `.synapse`, `synapse_export.*`
- Virtual environments: `.venv`, `venv`, `env`, `virtualenv`
- Package dependencies: `node_modules`, `site-packages`, `vendor`, `bower_components`
- Build outputs: `dist`, `build`, `out`, `target`, `bin`, `obj`
- Cache directories: `__pycache__`, `.pytest_cache`, `.mypy_cache`, `.cache`, `.parcel-cache`
- Binary and media files: `.exe`, `.dll`, `.so`, `.zip`, `.tar`, `.gz`, `.png`, `.jpg`, `.pdf`, etc.
- Large files exceeding the maximum file size cap (default: 10 MB)

---

## 6. Exit Codes

Synapse adheres to standard UNIX CLI exit codes:
- `0`: Success. Operation completed cleanly.
- `1`: Operational error (e.g., repository not initialized, non-Git directory, corrupt DB, file read error).
- `2`: CLI usage / argument syntax error (e.g., missing required argument, invalid command).

---

## 7. Supported Languages & Extracted Entities

| Language | Extensions | Extracted Symbols | Relationships Captured |
|---|---|---|---|
| **Python** | `.py` | Classes, Methods, Functions | `CONTAINS`, `DEFINES`, `INHERITS_FROM`, `CALLS`, `IMPORTS`, `REFERENCES` |
| **JavaScript** | `.js`, `.jsx`, `.mjs`, `.cjs` | Classes, Methods, Functions | `CONTAINS`, `DEFINES`, `INHERITS_FROM` (class extends), `CALLS`, `IMPORTS`, `REFERENCES` |
| **TypeScript / TSX** | `.ts`, `.tsx` | Classes, Interfaces, Methods, Functions | `CONTAINS`, `DEFINES`, `INHERITS_FROM` (extends / implements), `CALLS`, `IMPORTS`, `REFERENCES` |

---

## 8. Explicit Limitations

Synapse is designed to provide **provable, statically defensible** structural representations without inventing runtime behavior:
- **Dynamic Invocations**: Dynamic dispatch, runtime `getattr()` / `eval()`, dynamic imports (`import()`, `require(variable)`), and metaprogramming constructs remain marked as `unresolved`.
- **Runtime Reflection**: Reflection-based dependency injection and indirect plugin registries cannot be inferred statically.
- **Decorators**: Decorators that mutate function signatures or wrap callable targets are indexed syntactically; runtime wrapper execution paths are not fabricated.
- **Cross-Package Externals**: External package dependencies (e.g., standard library, third-party libraries outside the repository) are identified as module imports, but their external internal symbol graphs are not parsed.
- **Re-exports**: Multi-level star re-exports (`export * from '...'`) across nested modules are tracked up to direct resolvable symbol bindings.

---

## 9. Recovery & Maintenance

If the index database is ever corrupted or state needs to be resynchronized:
```bash
# Force a full rebuild of the repository index from HEAD
synapse index --rebuild
```

If `.synapse/index.db` is physically damaged or truncated:
```bash
# Remove corrupted database file and re-initialize
rm .synapse/index.db
synapse init
synapse index
```

---

## 10. Development & Testing

Synapse includes an exhaustive test suite covering all 9 engineering phases:
```bash
# Run the full test suite
pytest tests/ -v
```

All 70 tests run locally with zero network calls, zero LLM dependencies, and automatic cleanup of temporary Git repositories.

---

## 11. License

MIT License. See [LICENSE](LICENSE) for details.
