Metadata-Version: 2.4
Name: explain-codebase
Version: 0.1.0
Summary: CLI tool for quickly mapping the architecture of an unfamiliar repository.
Project-URL: Homepage, https://github.com/danyasync/explain-codebase
Project-URL: Repository, https://github.com/danyasync/explain-codebase
Project-URL: Issues, https://github.com/danyasync/explain-codebase/issues
Author: danyasync
License: MIT License
        
        Copyright (c) 2026 danyasync
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.10
Requires-Dist: networkx>=3.3
Requires-Dist: pydantic>=2.7
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == 'dev'
Description-Content-Type: text/markdown

# Explain Codebase

CLI tool that analyzes any repository and explains its architecture, entrypoints, dependencies, and impact of changes.

`explain-codebase` analyzes a repository and helps developers understand unfamiliar projects faster by showing how the system is structured and where execution likely starts.

It works with both local folders and public GitHub repositories.

---

## Why

When opening a new repository, it is often unclear:

- where the application starts
- which modules are central
- which files interact with external systems
- what files are risky to modify

`explain-codebase` scans the project, builds a dependency graph, detects architectural signals, and produces a compact CLI overview that helps you understand the codebase faster.

---

## Installation

```bash
pip install explain-codebase
```

For local development:

```bash
pip install -e .[dev]
```

## Quick Start

Analyze the current repository:

```bash
explain-codebase .
```

Verbose architecture output:

```bash
explain-codebase . --verbose
```

Deep architecture analysis:

```bash
explain-codebase . --deep
```

Analyze a GitHub repository:

```bash
explain-codebase https://github.com/user/repo
```

## Example Output

```text
Explain Codebase
--------------------------------

Repository

  Path        C:\Projects\orders-api
  Type        Python backend service
  Language    python
  Files       7

Architecture

  Entrypoints        1
  Core modules       5
  Side effects       4

Suggested starting point

  api_server.py

Run with --verbose to see full architecture
```

Verbose mode provides a deeper architecture view:

```text
Execution flow

api_server.py
|- routes/order_routes.py
|- services/order_service.py
|  |- repositories/order_repository.py
|  \- clients/warehouse_client.py
\- middleware/auth_guard.py
```

## Features

- Analyze local folders and public GitHub repositories
- Detect project language and project type
- Detect entrypoints automatically
- Rank core modules by dependency usage
- Infer likely execution flow
- Detect modules that interact with database, network, filesystem, or cache
- Detect architecture folders such as `services`, `repositories`, `routes`, and `models`
- Detect large modules and highly coupled files
- Detect architecture smells such as circular dependencies
- Generate dependency graph visualizations
- Generate HTML architecture reports
- Explain a single file in project context
- Suggest onboarding reading paths
- Support CI mode for architecture checks

## Common Commands

Analyze a repository:

```bash
explain-codebase .
```

Verbose architecture output:

```bash
explain-codebase . --verbose
```

Deep architecture analysis:

```bash
explain-codebase . --deep
```

Suggest a reading order for a new developer:

```bash
explain-codebase onboarding .
```

Explain a single file:

```bash
explain-codebase file src/services/order_service.ts
```

Generate a dependency graph:

```bash
explain-codebase . --graph
```

Generate an HTML architecture report:

```bash
explain-codebase . --report
```

Run in CI mode:

```bash
explain-codebase . --ci
```

## Remote Repositories

You can analyze a public GitHub repository directly:

```bash
explain-codebase https://github.com/user/repo
```

The tool will:

1. Resolve the repository
2. Check that it exists and is publicly accessible
3. Ask for confirmation before cloning
4. Clone it into a temporary workspace
5. Run the analysis
6. Remove the temporary workspace automatically

## Output Modes

Default mode shows a compact overview:

```bash
explain-codebase .
```

Verbose mode shows the full architecture structure:

```bash
explain-codebase . --verbose
```

Deep mode focuses on architecture risks and potential issues:

```bash
explain-codebase . --deep
```
