Metadata-Version: 2.4
Name: brieflook
Version: 0.2.0
Summary: Understand any repository in minutes.
Project-URL: Homepage, https://github.com/nabilkhan-01/brieflook
Project-URL: Repository, https://github.com/nabilkhan-01/brieflook
Project-URL: Issues, https://github.com/nabilkhan-01/brieflook/issues
License: MIT
License-File: LICENSE
Keywords: cli,codebase,developer-tools,onboarding,repository
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.13
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: rich>=14.1.0
Requires-Dist: typer>=0.17.4
Description-Content-Type: text/markdown

# BriefLook

[![PyPI Version](https://img.shields.io/pypi/v/brieflook.svg)](https://pypi.org/project/brieflook/)
[![Python Version](https://img.shields.io/pypi/pyversions/brieflook.svg)](https://pypi.org/project/brieflook/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Tests](https://github.com/nabilkhan-01/brieflook/actions/workflows/test.yml/badge.svg)](https://github.com/nabilkhan-01/brieflook/actions)

> **See through any codebase in seconds.**

Built for developers joining unfamiliar repositories.

BriefLook is a deterministic repository X-ray CLI that answers the core onboarding questions developers ask when opening a new project. It analyzes explicit repository evidence to produce fast, repeatable results—completely offline, without AI, and without guesswork.

---

## Why BriefLook?

Understanding an unfamiliar codebase often takes longer than writing code.

Developers typically switch between documentation, project configuration, source files, and other tools to answer basic onboarding questions:

- **What kind of project is this?**
- **What do I need before it will run?**
- **Where should I start reading?**
- **Where does execution begin?**
- **How do I build, run, and test it?**

BriefLook answers these questions by analyzing repository evidence directly—from project configuration, lockfiles, container specifications, and source structure.

Every reported fact is traceable to a repository artifact. If BriefLook cannot prove something from the repository, it does not report it.

---

## Key Features

| Onboarding Question | Feature | Information Extracted |
|---|---|---|
| *"What kind of project is this?"* | **Repository Identity** | Language, Framework, Package Manager, Project Type |
| *"What exactly do I need before this project will run?"* | **Quick Start** | Runtime versions (`Dockerfile`, `pyproject.toml`, `.nvmrc`), Docker, Infrastructure Services (`PostgreSQL`, `Redis`, `MongoDB`) |
| *"Where should I begin reading?"* | **Start Here** | Core documentation and configuration files ranked with evidence-based reasons |
| *"Where does execution begin?"* | **Entry Points** | Application bootstrap files (`__main__.py`, `main.go`, `server.js`, Next.js pages) |
| *"How do I build, run and test this project?"* | **Run Guide** | Authoritative install, run, and test commands derived from project configuration |
| *"Where are the major parts of the repository?"* | **Project Structure** | High-level directory purposes (`src/`, `tests/`, `docs/`, etc.) |

---

## Output Example

Run BriefLook on any local repository:

```bash
brieflook .
```

```text
          Repository           
+-----------------------------+
| Property        | Value     |
|-----------------+-----------|
| Name            | BRIEFLOOK |
| Language        | Python    |
| Framework       | Typer CLI |
| Package Manager | uv        |
| Project Type    | CLI Tool  |
+-----------------------------+

                     Quick Start                      
+----------------------------------------------------+
| Prerequisite | Version | Reason                    |
|--------------+---------+---------------------------|
| Python       | >=3.11  | Defined in pyproject.toml |
+----------------------------------------------------+

                                  Start Here                                   
+-----------------------------------------------------------------------------+
| # | Path                      | Reason                                      |
|---+---------------------------+---------------------------------------------|
| 1 | README.md                 | Repository documentation                    |
| 2 | src/brieflook/__main__.py | Entry point for this cli tool.              |
| 3 | pyproject.toml            | Defines dependencies for this project,      |
|   |                           | managed with uv.                            |
+-----------------------------------------------------------------------------+

                         Entry Points                          
+-------------------------------------------------------------+
| # | Path                      | Reason                      |
|---+---------------------------+-----------------------------|
| 1 | src/brieflook/__main__.py | Python package entry point. |
+-------------------------------------------------------------+

          Run Guide           
+----------------------------+
| Step    | Command          |
|---------+------------------|
| Install | uv sync          |
| Run     | uv run brieflook |
| Test    | pytest           |
+----------------------------+

             Project Structure             
+-----------------------------------------+
| # | Directory | Purpose                 |
|---+-----------+-------------------------|
| 1 | src/      | Application source code |
| 2 | tests/    | Project tests           |
+-----------------------------------------+
```

---

## Product Philosophy

1. **One Onboarding Question per Feature:** Every feature exists to answer exactly one real onboarding question and save meaningful developer time.
2. **Evidence over Guessing:** Every output fact is backed by explicit repository evidence (config files, lockfiles, container specs). No heuristics, no guessing.
3. **Deterministic Analysis:** Fast, offline, static analysis with zero AI hallucination.
4. **Explicit Evidence:** Every reported fact can be traced back to a specific repository artifact. If BriefLook cannot prove something, it does not report it.

---

## Installation & Usage

### For Users

Install via `uv` or `pip`:

```bash
uv tool install brieflook
# or
pip install brieflook
```

Run BriefLook on any target repository:

```bash
brieflook /path/to/repository
```

### For Contributors

Clone the repository and set up a local development environment:

```bash
git clone https://github.com/nabilkhan-01/brieflook.git
cd brieflook

uv sync
uv run brieflook .
```

---

## License

[MIT](LICENSE)
