synaptic-graph 0.1.0__tar.gz

synaptic_graph-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+lib/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+*.html
+*.svg
+!assets/demo.svg

synaptic_graph-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: synaptic-graph
+Version: 0.1.0
+Summary: Visualize the dependency graph of any Python project — internal imports, cloud SDKs and HTTP calls.
+Project-URL: Homepage, https://github.com/darkvius/synaptic
+Project-URL: Repository, https://github.com/darkvius/synaptic
+Project-URL: Issues, https://github.com/darkvius/synaptic/issues
+License: MIT
+Keywords: architecture,ast,dependencies,graph,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: graphviz>=0.20
+Requires-Dist: networkx>=3.2
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyvis>=0.3
+Requires-Dist: rich>=13
+Requires-Dist: textual>=0.80
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="assets/demo.svg" alt="synaptic demo" width="100%"/>
+
+# synaptic
+
+**Visualize the dependency graph of any Python project.**  
+Internal imports · Cloud SDKs · HTTP clients · Circular deps — all in one command.
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-4F8EF7?style=flat-square&logo=python&logoColor=white)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-2ecc71?style=flat-square)](LICENSE)
+[![Built with Typer](https://img.shields.io/badge/CLI-Typer-E84393?style=flat-square)](https://typer.tiangolo.com)
+[![Powered by Rich](https://img.shields.io/badge/output-Rich-FF9900?style=flat-square)](https://rich.readthedocs.io)
+
+</div>
+
+---
+
+## Features
+
+- **Static AST analysis** — no runtime execution needed
+- **Internal imports** — maps every `import` and `from X import Y` across your codebase
+- **Cloud SDK detection** — identifies AWS (`boto3`), GCP (`google.cloud`, `firebase_admin`) and Azure (`azure.*`) usage
+- **HTTP client detection** — flags modules using `requests`, `httpx`, `aiohttp`, `urllib3` and more
+- **Circular dependency highlighting** — broken cycles rendered in red
+- **Two output formats** — interactive HTML (`pyvis`) or static SVG/PNG (`graphviz`)
+- **Rich terminal output** — live progress, color-coded summary
+
+---
+
+## Installation
+
+```bash
+pip install synaptic
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/your-username/synaptic
+cd synaptic
+pip install -e .
+```
+
+> **Requirements:** Python 3.10+, `graphviz` binary installed on your system (`apt install graphviz` / `brew install graphviz`).
+
+---
+
+## Quick start
+
+```bash
+# Interactive HTML graph (default)
+synaptic scan ./my-project
+
+# Custom output path
+synaptic scan ./my-project --output architecture.html
+
+# SVG with circular dependency highlighting
+synaptic scan ./my-project --output graph.svg --circular
+
+# Skip cloud and HTTP detection, filter stdlib
+synaptic scan ./my-project --no-cloud --no-http --filter-stdlib
+
+# Include test files in the scan
+synaptic scan ./my-project --tests
+```
+
+---
+
+## Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--output`, `-o` | `synaptic_graph.html` | Output file (`.html` or `.svg`) |
+| `--cloud / --no-cloud` | `on` | Detect AWS / GCP / Azure SDKs |
+| `--http / --no-http` | `on` | Detect HTTP client libraries |
+| `--tests / --no-tests` | `off` | Include test files |
+| `--filter-stdlib / --no-filter-stdlib` | `on` | Exclude Python stdlib from graph |
+| `--filter-external / --no-filter-external` | `off` | Exclude third-party packages |
+| `--circular`, `-c` | `off` | Highlight circular dependencies in red |
+| `--version`, `-v` | — | Show version and exit |
+
+---
+
+## Architecture
+
+```
+synaptic/
+├── cli.py             # Typer CLI + Rich output
+├── scanner.py         # Recursive .py file discovery
+├── parser.py          # AST-based import analysis
+├── cloud_detector.py  # AWS / GCP / Azure SDK detection
+├── http_detector.py   # HTTP client library detection
+├── graph.py           # networkx graph + graphviz / pyvis rendering
+└── utils.py           # Shared helpers
+```
+
+---
+
+## Node types
+
+| Color | Meaning |
+|---|---|
+| 🔵 Blue | Internal project module |
+| 🟠 Orange | AWS / GCP / Azure SDK |
+| 🩷 Pink | HTTP client (requests, httpx…) |
+| ⚫ Grey | Stdlib / external package |
+| 🔴 Red edge | Circular dependency |
+
+---
+
+## License
+
+MIT © 2024

synaptic_graph-0.1.0/README.md

@@ -0,0 +1,114 @@
+<div align="center">
+
+<img src="assets/demo.svg" alt="synaptic demo" width="100%"/>
+
+# synaptic
+
+**Visualize the dependency graph of any Python project.**  
+Internal imports · Cloud SDKs · HTTP clients · Circular deps — all in one command.
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-4F8EF7?style=flat-square&logo=python&logoColor=white)](https://python.org)
+[![License](https://img.shields.io/badge/license-MIT-2ecc71?style=flat-square)](LICENSE)
+[![Built with Typer](https://img.shields.io/badge/CLI-Typer-E84393?style=flat-square)](https://typer.tiangolo.com)
+[![Powered by Rich](https://img.shields.io/badge/output-Rich-FF9900?style=flat-square)](https://rich.readthedocs.io)
+
+</div>
+
+---
+
+## Features
+
+- **Static AST analysis** — no runtime execution needed
+- **Internal imports** — maps every `import` and `from X import Y` across your codebase
+- **Cloud SDK detection** — identifies AWS (`boto3`), GCP (`google.cloud`, `firebase_admin`) and Azure (`azure.*`) usage
+- **HTTP client detection** — flags modules using `requests`, `httpx`, `aiohttp`, `urllib3` and more
+- **Circular dependency highlighting** — broken cycles rendered in red
+- **Two output formats** — interactive HTML (`pyvis`) or static SVG/PNG (`graphviz`)
+- **Rich terminal output** — live progress, color-coded summary
+
+---
+
+## Installation
+
+```bash
+pip install synaptic
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/your-username/synaptic
+cd synaptic
+pip install -e .
+```
+
+> **Requirements:** Python 3.10+, `graphviz` binary installed on your system (`apt install graphviz` / `brew install graphviz`).
+
+---
+
+## Quick start
+
+```bash
+# Interactive HTML graph (default)
+synaptic scan ./my-project
+
+# Custom output path
+synaptic scan ./my-project --output architecture.html
+
+# SVG with circular dependency highlighting
+synaptic scan ./my-project --output graph.svg --circular
+
+# Skip cloud and HTTP detection, filter stdlib
+synaptic scan ./my-project --no-cloud --no-http --filter-stdlib
+
+# Include test files in the scan
+synaptic scan ./my-project --tests
+```
+
+---
+
+## Options
+
+| Flag | Default | Description |
+|---|---|---|
+| `--output`, `-o` | `synaptic_graph.html` | Output file (`.html` or `.svg`) |
+| `--cloud / --no-cloud` | `on` | Detect AWS / GCP / Azure SDKs |
+| `--http / --no-http` | `on` | Detect HTTP client libraries |
+| `--tests / --no-tests` | `off` | Include test files |
+| `--filter-stdlib / --no-filter-stdlib` | `on` | Exclude Python stdlib from graph |
+| `--filter-external / --no-filter-external` | `off` | Exclude third-party packages |
+| `--circular`, `-c` | `off` | Highlight circular dependencies in red |
+| `--version`, `-v` | — | Show version and exit |
+
+---
+
+## Architecture
+
+```
+synaptic/
+├── cli.py             # Typer CLI + Rich output
+├── scanner.py         # Recursive .py file discovery
+├── parser.py          # AST-based import analysis
+├── cloud_detector.py  # AWS / GCP / Azure SDK detection
+├── http_detector.py   # HTTP client library detection
+├── graph.py           # networkx graph + graphviz / pyvis rendering
+└── utils.py           # Shared helpers
+```
+
+---
+
+## Node types
+
+| Color | Meaning |
+|---|---|
+| 🔵 Blue | Internal project module |
+| 🟠 Orange | AWS / GCP / Azure SDK |
+| 🩷 Pink | HTTP client (requests, httpx…) |
+| ⚫ Grey | Stdlib / external package |
+| 🔴 Red edge | Circular dependency |
+
+---
+
+## License
+
+MIT © 2024

synaptic_graph-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "synaptic-graph"
+version = "0.1.0"
+description = "Visualize the dependency graph of any Python project — internal imports, cloud SDKs and HTTP calls."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+keywords = ["dependencies", "graph", "architecture", "visualization", "ast"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "typer>=0.12",
+    "rich>=13",
+    "graphviz>=0.20",
+    "pyvis>=0.3",
+    "networkx>=3.2",
+    "numpy>=1.24",
+    "textual>=0.80",
+]
+
+[project.urls]
+Homepage = "https://github.com/darkvius/synaptic"
+Repository = "https://github.com/darkvius/synaptic"
+Issues = "https://github.com/darkvius/synaptic/issues"
+
+[project.scripts]
+synaptic = "synaptic.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["synaptic"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "synaptic/",
+    "README.md",
+    "pyproject.toml",
+]

synaptic_graph-0.1.0/synaptic/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

synaptic_graph-0.1.0/synaptic/cli.py

@@ -0,0 +1,214 @@
+"""
+cli.py — Synaptic CLI built with Typer + Rich.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+import sys
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from rich import print as rprint
+
+from synaptic import __version__
+
+app = typer.Typer(
+    name="synaptic",
+    help="[bold cyan]synaptic[/] — visualize the dependency graph of any Python project.",
+    rich_markup_mode="rich",
+    add_completion=True,
+)
+
+console = Console()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        rprint(f"[bold cyan]synaptic[/] version [bold]{__version__}[/]")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Optional[bool] = typer.Option(
+        None, "--version", "-v",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    pass
+
+
+@app.command()
+def scan(
+    project: Path = typer.Argument(
+        ...,
+        help="Root path of the Python project to analyse.",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    output: Path = typer.Option(
+        Path("synaptic_graph.html"),
+        "--output", "-o",
+        help="Output file path. Extension determines format: .html (interactive) or .svg.",
+    ),
+    cloud: bool = typer.Option(True,  "--cloud/--no-cloud",  help="Detect AWS / GCP / Azure SDK usage."),
+    http:  bool = typer.Option(True,  "--http/--no-http",    help="Detect HTTP client library usage."),
+    tests: bool = typer.Option(False, "--tests/--no-tests",  help="Include test files in the scan."),
+    filter_stdlib:    bool = typer.Option(True,  "--filter-stdlib/--no-filter-stdlib",       help="Exclude Python stdlib modules from the graph."),
+    filter_external:  bool = typer.Option(False, "--filter-external/--no-filter-external",   help="Exclude third-party (non-project) modules from the graph."),
+    circular: bool = typer.Option(False, "--circular", "-c", help="Highlight circular dependencies in red."),
+) -> None:
+    """Scan *PROJECT* and generate a dependency graph."""
+
+    console.print(
+        Panel.fit(
+            f"[bold cyan]synaptic[/] [dim]v{__version__}[/]\n"
+            f"[dim]Scanning:[/] [bold]{project}[/]",
+            border_style="cyan",
+        )
+    )
+
+    with Progress(SpinnerColumn(), TextColumn("[progress.description]{task.description}"), console=console) as progress:
+
+        # 1. Scan files
+        task = progress.add_task("Scanning .py files...", total=None)
+        from synaptic.scanner import scan as do_scan
+        files = do_scan(project, include_tests=tests)
+        progress.update(task, description=f"[green]Found {len(files)} Python files[/]", completed=True)
+
+        if not files:
+            console.print("[yellow]No Python files found. Is the path correct?[/]")
+            raise typer.Exit(1)
+
+        # 2. Parse imports
+        task = progress.add_task("Parsing imports (AST)...", total=None)
+        from synaptic.parser import parse_project
+        edges = parse_project(files, project)
+        progress.update(task, description=f"[green]Parsed {len(edges)} import edges[/]", completed=True)
+
+        # 3. Cloud detection
+        cloud_deps = []
+        if cloud:
+            task = progress.add_task("Detecting cloud SDKs...", total=None)
+            from synaptic.cloud_detector import detect as detect_cloud
+            cloud_deps = detect_cloud(edges)
+            progress.update(task, description=f"[green]Found {len(cloud_deps)} cloud dependencies[/]", completed=True)
+
+        # 4. HTTP detection
+        http_deps = []
+        if http:
+            task = progress.add_task("Detecting HTTP clients...", total=None)
+            from synaptic.http_detector import detect as detect_http
+            http_deps = detect_http(edges)
+            progress.update(task, description=f"[green]Found {len(http_deps)} HTTP dependencies[/]", completed=True)
+
+        # 5. Build graph
+        task = progress.add_task("Building graph...", total=None)
+        from synaptic.utils import get_stdlib_modules, resolve_internal_modules, choose_output_format
+        from synaptic.graph import build, render_html, render_svg
+
+        internal_modules = resolve_internal_modules(files, project)
+        stdlib_modules = get_stdlib_modules()
+
+        G = build(
+            edges=edges,
+            cloud_deps=cloud_deps,
+            http_deps=http_deps,
+            internal_modules=internal_modules,
+            stdlib_modules=stdlib_modules,
+            filter_stdlib=filter_stdlib,
+            filter_external=filter_external,
+            highlight_circular=circular,
+        )
+        progress.update(task, description=f"[green]Graph: {G.number_of_nodes()} nodes, {G.number_of_edges()} edges[/]", completed=True)
+
+        # 6. Render
+        fmt = choose_output_format(output)
+        task = progress.add_task(f"Rendering {fmt.upper()}...", total=None)
+        if fmt == "html":
+            render_html(G, output)
+        else:
+            render_svg(G, output)
+        progress.update(task, description=f"[green]Saved to {output}[/]", completed=True)
+
+    # Summary
+    console.print()
+    console.print(
+        Panel(
+            f"[bold green]Done![/]\n\n"
+            f"  [dim]Files scanned:[/]     [bold]{len(files)}[/]\n"
+            f"  [dim]Import edges:[/]      [bold]{len(edges)}[/]\n"
+            f"  [dim]Cloud deps:[/]        [bold]{len(cloud_deps)}[/]\n"
+            f"  [dim]HTTP deps:[/]         [bold]{len(http_deps)}[/]\n"
+            f"  [dim]Graph nodes:[/]       [bold]{G.number_of_nodes()}[/]\n"
+            f"  [dim]Graph edges:[/]       [bold]{G.number_of_edges()}[/]\n\n"
+            f"  [dim]Output:[/] [bold cyan]{output.resolve()}[/]",
+            title="[bold cyan]synaptic[/]",
+            border_style="green",
+        )
+    )
+
+
+@app.command()
+def tui(
+    project: Path = typer.Argument(
+        ...,
+        help="Root path of the Python project to analyse.",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+    cloud: bool = typer.Option(True,  "--cloud/--no-cloud",  help="Detect AWS / GCP / Azure SDK usage."),
+    http:  bool = typer.Option(True,  "--http/--no-http",    help="Detect HTTP client library usage."),
+    tests: bool = typer.Option(False, "--tests/--no-tests",  help="Include test files in the scan."),
+    filter_stdlib:   bool = typer.Option(True,  "--filter-stdlib/--no-filter-stdlib",     help="Exclude stdlib modules from the graph."),
+    filter_external: bool = typer.Option(False, "--filter-external/--no-filter-external", help="Exclude third-party modules."),
+    circular: bool = typer.Option(True, "--circular/--no-circular", help="Highlight circular dependencies."),
+) -> None:
+    """Launch the interactive TUI graph explorer for *PROJECT*."""
+    from synaptic.scanner import scan as do_scan
+    from synaptic.parser import parse_project
+    from synaptic.cloud_detector import detect as detect_cloud
+    from synaptic.http_detector import detect as detect_http
+    from synaptic.graph import build
+    from synaptic.utils import get_stdlib_modules, resolve_internal_modules
+    from synaptic.tui import launch
+
+    with console.status("[cyan]Building graph…[/]"):
+        files = do_scan(project, include_tests=tests)
+        if not files:
+            console.print("[yellow]No Python files found.[/]")
+            raise typer.Exit(1)
+
+        edges = parse_project(files, project)
+        cloud_deps = detect_cloud(edges) if cloud else []
+        http_deps = detect_http(edges) if http else []
+
+        internal_modules = resolve_internal_modules(files, project)
+        stdlib_modules = get_stdlib_modules()
+
+        G = build(
+            edges=edges,
+            cloud_deps=cloud_deps,
+            http_deps=http_deps,
+            internal_modules=internal_modules,
+            stdlib_modules=stdlib_modules,
+            filter_stdlib=filter_stdlib,
+            filter_external=filter_external,
+            highlight_circular=circular,
+        )
+
+    launch(G, project)
+
+
+if __name__ == "__main__":
+    app()

synaptic_graph-0.1.0/synaptic/cloud_detector.py

@@ -0,0 +1,47 @@
+"""
+cloud_detector.py — Identify cloud SDK usage from import edges.
+"""
+
+from dataclasses import dataclass
+from synaptic.parser import ImportEdge
+
+# Map root package prefixes → (provider, service label)
+CLOUD_SIGNATURES: dict[str, tuple[str, str]] = {
+    "boto3":            ("AWS", "boto3"),
+    "botocore":         ("AWS", "botocore"),
+    "aiobotocore":      ("AWS", "aiobotocore"),
+    "google.cloud":     ("GCP", "google-cloud"),
+    "google.api_core":  ("GCP", "google-api-core"),
+    "firebase_admin":   ("GCP", "firebase-admin"),
+    "googleapiclient":  ("GCP", "google-api-python-client"),
+    "azure":            ("Azure", "azure-sdk"),
+    "msrest":           ("Azure", "msrest"),
+}
+
+
+@dataclass
+class CloudDependency:
+    source: str       # module that imports the SDK
+    provider: str     # AWS | GCP | Azure
+    sdk: str          # human-readable SDK name
+    raw_import: str   # original import target string
+
+
+def detect(edges: list[ImportEdge]) -> list[CloudDependency]:
+    """Return CloudDependency entries found in the import edge list."""
+    found: list[CloudDependency] = []
+
+    for edge in edges:
+        for prefix, (provider, sdk) in CLOUD_SIGNATURES.items():
+            if edge.target == prefix or edge.target.startswith(prefix + "."):
+                found.append(
+                    CloudDependency(
+                        source=edge.source,
+                        provider=provider,
+                        sdk=sdk,
+                        raw_import=edge.target,
+                    )
+                )
+                break  # first match wins
+
+    return found