synap-git 2.4.1__tar.gz → 2.6.0__tar.gz

{synap_git-2.4.1 → synap_git-2.6.0}/.gitignore

@@ -22,14 +22,11 @@ build/
 *.db-shm
 .env
 .env.*
+!.env.example
 .env.local
 .synapse/
 .synapse/*-wal
 .synapse/*-shm
-config.json
-status.json
-fix_exc.py
-test_embed.py
 .vscode/
 .idea/
 *.log

{synap_git-2.4.1 → synap_git-2.6.0}/CHANGELOG.md

@@ -5,6 +5,40 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.0] - 2026-11-01
+
+### Specialist Implementation Sprint & Production-Quality Engineering
+- **Shared Runtime Snapshot Caching & Event Stream Isolation**: Added 2-second TTL caching to `/api/status` and `/api/v1/events` avoiding redundant Git child processes and SQLite queries; added client disconnect detection (`await request.is_disconnected()`) in SSE loop to prevent CPU leaks on closed browser tabs.
+- **Compact FastMCP Session Preamble & Batch Extraction**: Reduced `get_session_preamble()` prompt overhead to <150 tokens preserving negative constraints and branch checkpoints; added `read_symbols(symbols=[...])` for single-roundtrip multi-symbol extraction.
+- **Pipe-Friendly CLI & Machine-Parsable JSON**: Added interactive TTY autodetection in `_print_formatted()` emitting unstyled plain text and pipe-delimited tables when redirected, plus `--json` flags to `synap status`, `synap diff`, `synap blast`, and `synap hubs`.
+- **Merge/Rebase In-Progress Indexing Guards**: Prevented conflict marker corruption (`<<<<<<< HEAD`) by auto-pausing the indexing engine during active `MERGE_HEAD`, `REBASE_HEAD`, or `BISECT_HEAD` operations.
+- **Proportional Context Budgeting & Tokenization**: Replaced fixed 600-token safety margin with dynamic proportional allocation (`12%` budget cap) and added 2-character identifier preservation (`db`, `id`, `ip`, `ui`, `tx`) with camelCase/snake_case sub-tokenization.
+- **Storage Self-Healing Isolation**: Enforced that `recover_if_corrupted()` only resets database files upon explicit `PRAGMA quick_check` B-tree failure, never on transient concurrency lock timeouts.
+- **Background UI Throttling**: Paused dashboard polling and event consumption when browser tab is inactive via Page Visibility API.
+- **Packaging & Version Synchronization**: Unified package version `2.6.0` across `pyproject.toml` and `synap_git/__init__.py`, and pruned legacy unused dependencies.
+
+## [2.5.0] - 2026-11-01
+
+### Major System Transformation & Performance Acceleration (10-Specialist Mission)
+- **193x Faster Graph Traversal**: Replaced full-table scans in `get_neighborhood()` with `min_distances` CTE pre-aggregation and added composite covering indexes (`idx_edges_src_tgt`, `idx_edges_tgt_src`, `idx_symbols_start_end`).
+- **Personalized PageRank (PPR)**: Pure-Python PPR implementation accelerated 2.36x with integer index arrays, biasing ranking towards active dirty files to identify architectural hubs.
+- **Git-Aware Blast Radius Analysis**: Diff interval mapping (`get_dirty_diff_ranges()`) across untracked, staged, and unstaged modifications, correlating touched lines to AST symbols, callers, and impacted test suites.
+- **Git Worktree & Detached HEAD Resolution**: Safe worktree support resolving `gitdir:` and `commondir:`, robust checkout classification during detached HEAD and rebases, and clean ghost file pruning on branch checkout transitions.
+- **Deterministic AST Code Skeletonization**: Reverse-order byte-slicing across Python, JS/TS, Go, Rust, Java, C/C++ yielding 81%–90% token reduction with nested closure preservation.
+- **Zero-Corruption SQLite Recovery**: Hardened `recover_if_corrupted()` to never wipe database files on transient lock contention or timeouts, and added PRAGMA tuning (`busy_timeout=30000`, `cache_size=-64000`, `temp_store=MEMORY`).
+- **FastMCP Tool Diet**: Upgraded 23 FastMCP tools with clean fallback defaults, directional aliases (`get_callers`, `get_callees`), `read_symbol`, `get_diff`, and `get_test_recommendations`.
+- **New Advanced CLI Commands**: Added `synap blast`, `synap hubs`, `synap outline`, `synap diff`, `synap test`, `synap explain`, `synap pack`, interactive status dashboard on zero arguments, and `--fix` / `--context` support in `synap doctor`.
+- **Web UI Overhaul**: Revamped diagnostic dashboard with zero emojis, dark/light themes, `/` keyboard shortcut search, interactive symbol inspector modal, live blast radius table, PageRank hubs table, and one-click lesson approval/rejection.
+- **Dead Code Pruning**: Purged obsolete `retrieval/memory.py` module, redundant CLI wrappers, and standardized soft-rejection semantics across Web UI and CLI.
+- **10-Specialist Improvement Audit**: Added authoritative audit roadmap (`docs/IMPROVEMENT_AUDIT.md`), architecture specifications (`docs/architecture/system-overview.md`), research literature review (`docs/research/benchmarks-and-literature.md`), and monorepo stress methodology (`docs/benchmarks/monorepo-stress-methodology.md`).
+- **Critical Concurrency & Safety Fixes**:
+  - Atomic wiki task dequeuing in SQLite via `UPDATE ... RETURNING *` inside `BEGIN IMMEDIATE`.
+  - JSONC comment parsing and `.bak` backups in `_inject_mcp_config` to prevent IDE config wiping.
+  - Subdirectory CLI execution automatically resolves repository root via `GitRepository.find_root`.
+  - Indexing suspended during active merge conflicts (`MERGE_HEAD`), rebases, and bisects.
+  - Proportional token budgeting (`min(500, int(max_tokens * 0.15))`) and preserved $\ge 2$ char tokens in lexical search.
+  - Web UI polling throttled when tab is backgrounded via Page Visibility API.
+
 ## [2.4.1] - 2026-09-11
 
 ### Security, Protocol & Architecture Hardening (Audit Remediation)

synap_git-2.6.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: synap-git
+Version: 2.6.0
+Summary: Persistent structural context infrastructure for AI coding agents.
+Project-URL: Homepage, https://github.com/saahilpal/synapse
+Project-URL: Repository, https://github.com/saahilpal/synapse
+Project-URL: Issues, https://github.com/saahilpal/synapse/issues
+Project-URL: Changelog, https://github.com/saahilpal/synapse/blob/main/CHANGELOG.md
+Author: Synap contributors
+License: Apache-2.0
+License-File: LICENSE.md
+Keywords: ai,context,developer-tools,git,mcp,repository-indexing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: click==8.1.8
+Requires-Dist: fastapi==0.115.11
+Requires-Dist: gitpython==3.1.44
+Requires-Dist: httpx==0.28.1
+Requires-Dist: keyring==25.6.0
+Requires-Dist: mcp==1.3.0
+Requires-Dist: msgpack==1.1.0
+Requires-Dist: packaging>=24.0
+Requires-Dist: prompt-toolkit<3.0.44
+Requires-Dist: pydantic-settings==2.8.1
+Requires-Dist: pydantic==2.10.6
+Requires-Dist: questionary==2.1.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: structlog==25.1.0
+Requires-Dist: tiktoken==0.9.0
+Requires-Dist: tree-sitter-languages==1.10.2
+Requires-Dist: tree-sitter==0.20.4
+Requires-Dist: typer==0.15.1
+Requires-Dist: uvicorn==0.34.0
+Requires-Dist: watchdog>=6.0.0
+Provides-Extra: dev
+Requires-Dist: bandit==1.8.3; extra == 'dev'
+Requires-Dist: mypy==1.15.0; extra == 'dev'
+Requires-Dist: pre-commit==4.1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio==0.25.3; extra == 'dev'
+Requires-Dist: pytest-cov==6.0.0; extra == 'dev'
+Requires-Dist: pytest-timeout==2.3.1; extra == 'dev'
+Requires-Dist: pytest==8.3.4; extra == 'dev'
+Requires-Dist: ruff==0.9.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Synapse
+
+> Fast, local, zero-cost structural context engine for AI coding agents.
+
+[![CI Status](https://github.com/saahilpal/synapse/actions/workflows/ci.yml/badge.svg)](https://github.com/saahilpal/synapse/actions)
+[![Version](https://img.shields.io/pypi/v/synap-git?color=3b82f6)](https://pypi.org/project/synap-git/)
+[![Python Version](https://img.shields.io/pypi/pyversions/synap-git)](https://pypi.org/project/synap-git/)
+[![License](https://img.shields.io/github/license/saahilpal/synapse?color=cbd5e1)](LICENSE.md)
+
+---
+
+## ⚡ 5-Second Quickstart
+
+Install Synapse and automatically configure your IDE (Cursor, Claude Code, Cline, Windsurf):
+
+```bash
+pip install synap-git
+synap install
+```
+
+Done. Synapse indexes your repository with Tree-sitter, installs zero-daemon Git hooks for automatic reindexing, and registers MCP server endpoints.
+
+---
+
+## Why Synapse?
+
+| Feature | Synapse | Repomix | Aider | Cursor / Cline Default |
+| :--- | :---: | :---: | :---: | :---: |
+| **API Cost** | **100% Free (Zero)** | 100% Free | Burns Tokens | Cloud Token Usage |
+| **Graph Intelligence** | **AST Symbol & Edge Graph** | None (Flat Dump) | Repo Map (CTags) | Vector Embeddings |
+| **Code Skeletonization** | **85% Token Reduction** | None (Raw Code) | Line Truncation | Chunk Slicing |
+| **Git Blast Radius** | **Instant Callers & Tests** | None | Diff Only | None |
+| **Architectural Hubs** | **Personalized PageRank** | None | Static Frequency | None |
+| **Working Memory** | **Persistent Checkpoints** | None | Ephemeral Chat | Ephemeral Session |
+| **Runtime Footprint** | **Zero-Daemon Hook Mode** | CLI Only | CLI Process | Background Indexer |
+
+---
+
+## Architecture
+
+```mermaid
+flowchart TD
+    A[AI Coding Agent / IDE<br>Cursor · Claude Code · Cline · Aider] -->|MCP stdio / CLI| B[Synapse Engine]
+    B --> C[AST Skeletonizer<br>85% Token Reduction]
+    B --> D[Git State & Blast Radius<br>Diff Line -> Callers -> Tests]
+    B --> E[Graph Engine & PageRank<br>Architectural Hubs]
+    B --> F[Working Memory & Lessons<br>Checkpoints & Anti-Regressions]
+    C & D & E & F --> G[(Local SQLite WAL DB<br>.synap/synap.db)]
+```
+
+For database schemas and CTE traversal queries, see [Architecture Internals](docs/architecture.md).
+
+---
+
+## Essential CLI Commands
+
+```bash
+# Print token-bounded startup context (< 750 tokens)
+synap context
+
+# Check modified symbols, direct callers, and impacted tests
+synap blast
+
+# Run only tests impacted by dirty git blast radius
+synap test
+
+# Deep structural symbol inspection (callers, dependencies, tests)
+synap explain my_function
+
+# Export token-budgeted prompt pack with AST skeletons (< 8k tokens)
+synap pack
+
+# Inspect structural AST skeleton of any file (strips bodies, keeps types/docstrings)
+synap skeleton src/my_module.py
+
+# Discover top architectural hubs via PageRank
+synap hubs
+
+# Search repository with hybrid structural ranking
+synap search "authentication flow"
+
+# Verify environment and system health
+synap doctor
+```
+
+Shorthand aliases supported: `synap ctx`, `synap blast`, `synap t`, `synap ex <sym>`, `synap sk <file>`, `synap hubs`, `synap doc`.
+
+---
+
+## MCP Tools for AI Agents
+
+When registered via `synap install`, AI agents gain direct access to these MCP tools:
+
+| MCP Tool | Purpose |
+| :--- | :--- |
+| `get_session_preamble()` | Token-optimized session startup context (< 750 tokens: active branch, dirty files, blast radius, hubs, lessons). |
+| `get_skeleton(file_path)` | Extracts function signatures, types, and docstrings without function bodies (85% token savings). |
+| `get_blast_radius()` | Computes impact radius of uncommitted git changes down to callers and test files. |
+| `get_callers(symbol)` | Finds all functions and modules that call or depend upon a symbol. |
+| `get_callees(symbol)` | Finds all functions and symbols called by a given symbol. |
+| `read_symbol(symbol)` | Reads exact lines and code of a specific function or class without reading the entire file. |
+| `get_diff()` | Unified git diff of uncommitted or staged changes. |
+| `get_test_recommendations()` | Discovers impacted test suites and provides recommended `pytest` commands. |
+| `create_checkpoint(doing)` | Saves thought process and dirty working state before complex refactors. |
+| `restore_checkpoint(id)` | Restores past checkpoint context after agent context compaction or memory wipes. |
+| `remember(key, content)` | Stores operational observations and environment facts in persistent memory. |
+
+---
+
+## License
+
+MIT © Saahil Pal

synap_git-2.6.0/README.md

@@ -0,0 +1,112 @@
+# Synapse
+
+> Fast, local, zero-cost structural context engine for AI coding agents.
+
+[![CI Status](https://github.com/saahilpal/synapse/actions/workflows/ci.yml/badge.svg)](https://github.com/saahilpal/synapse/actions)
+[![Version](https://img.shields.io/pypi/v/synap-git?color=3b82f6)](https://pypi.org/project/synap-git/)
+[![Python Version](https://img.shields.io/pypi/pyversions/synap-git)](https://pypi.org/project/synap-git/)
+[![License](https://img.shields.io/github/license/saahilpal/synapse?color=cbd5e1)](LICENSE.md)
+
+---
+
+## ⚡ 5-Second Quickstart
+
+Install Synapse and automatically configure your IDE (Cursor, Claude Code, Cline, Windsurf):
+
+```bash
+pip install synap-git
+synap install
+```
+
+Done. Synapse indexes your repository with Tree-sitter, installs zero-daemon Git hooks for automatic reindexing, and registers MCP server endpoints.
+
+---
+
+## Why Synapse?
+
+| Feature | Synapse | Repomix | Aider | Cursor / Cline Default |
+| :--- | :---: | :---: | :---: | :---: |
+| **API Cost** | **100% Free (Zero)** | 100% Free | Burns Tokens | Cloud Token Usage |
+| **Graph Intelligence** | **AST Symbol & Edge Graph** | None (Flat Dump) | Repo Map (CTags) | Vector Embeddings |
+| **Code Skeletonization** | **85% Token Reduction** | None (Raw Code) | Line Truncation | Chunk Slicing |
+| **Git Blast Radius** | **Instant Callers & Tests** | None | Diff Only | None |
+| **Architectural Hubs** | **Personalized PageRank** | None | Static Frequency | None |
+| **Working Memory** | **Persistent Checkpoints** | None | Ephemeral Chat | Ephemeral Session |
+| **Runtime Footprint** | **Zero-Daemon Hook Mode** | CLI Only | CLI Process | Background Indexer |
+
+---
+
+## Architecture
+
+```mermaid
+flowchart TD
+    A[AI Coding Agent / IDE<br>Cursor · Claude Code · Cline · Aider] -->|MCP stdio / CLI| B[Synapse Engine]
+    B --> C[AST Skeletonizer<br>85% Token Reduction]
+    B --> D[Git State & Blast Radius<br>Diff Line -> Callers -> Tests]
+    B --> E[Graph Engine & PageRank<br>Architectural Hubs]
+    B --> F[Working Memory & Lessons<br>Checkpoints & Anti-Regressions]
+    C & D & E & F --> G[(Local SQLite WAL DB<br>.synap/synap.db)]
+```
+
+For database schemas and CTE traversal queries, see [Architecture Internals](docs/architecture.md).
+
+---
+
+## Essential CLI Commands
+
+```bash
+# Print token-bounded startup context (< 750 tokens)
+synap context
+
+# Check modified symbols, direct callers, and impacted tests
+synap blast
+
+# Run only tests impacted by dirty git blast radius
+synap test
+
+# Deep structural symbol inspection (callers, dependencies, tests)
+synap explain my_function
+
+# Export token-budgeted prompt pack with AST skeletons (< 8k tokens)
+synap pack
+
+# Inspect structural AST skeleton of any file (strips bodies, keeps types/docstrings)
+synap skeleton src/my_module.py
+
+# Discover top architectural hubs via PageRank
+synap hubs
+
+# Search repository with hybrid structural ranking
+synap search "authentication flow"
+
+# Verify environment and system health
+synap doctor
+```
+
+Shorthand aliases supported: `synap ctx`, `synap blast`, `synap t`, `synap ex <sym>`, `synap sk <file>`, `synap hubs`, `synap doc`.
+
+---
+
+## MCP Tools for AI Agents
+
+When registered via `synap install`, AI agents gain direct access to these MCP tools:
+
+| MCP Tool | Purpose |
+| :--- | :--- |
+| `get_session_preamble()` | Token-optimized session startup context (< 750 tokens: active branch, dirty files, blast radius, hubs, lessons). |
+| `get_skeleton(file_path)` | Extracts function signatures, types, and docstrings without function bodies (85% token savings). |
+| `get_blast_radius()` | Computes impact radius of uncommitted git changes down to callers and test files. |
+| `get_callers(symbol)` | Finds all functions and modules that call or depend upon a symbol. |
+| `get_callees(symbol)` | Finds all functions and symbols called by a given symbol. |
+| `read_symbol(symbol)` | Reads exact lines and code of a specific function or class without reading the entire file. |
+| `get_diff()` | Unified git diff of uncommitted or staged changes. |
+| `get_test_recommendations()` | Discovers impacted test suites and provides recommended `pytest` commands. |
+| `create_checkpoint(doing)` | Saves thought process and dirty working state before complex refactors. |
+| `restore_checkpoint(id)` | Restores past checkpoint context after agent context compaction or memory wipes. |
+| `remember(key, content)` | Stores operational observations and environment facts in persistent memory. |
+
+---
+
+## License
+
+MIT © Saahil Pal

{synap_git-2.4.1 → synap_git-2.6.0}/pyproject.toml

@@ -24,13 +24,14 @@ dependencies = [
   "gitpython==3.1.44",
   "httpx==0.28.1",
   "keyring==25.6.0",
-  "markdown-it-py==3.0.0",
   "mcp==1.3.0",
   "msgpack==1.1.0",
+  "packaging>=24.0",
   "prompt-toolkit<3.0.44",
   "pydantic==2.10.6",
   "pydantic-settings==2.8.1",
   "questionary==2.1.0",
+  "rich>=13.7.0",
   "structlog==25.1.0",
   "tiktoken==0.9.0",
   "tree-sitter==0.20.4",

{synap_git-2.4.1 → synap_git-2.6.0}/src/synap_git/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "2.4.1"
+__version__ = "2.6.0"