Metadata-Version: 2.5
Name: brieflook
Version: 0.5.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: pyyaml<7,>=6.0.3
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)

> See through any codebase in seconds.

BriefLook is a deterministic CLI that turns an unfamiliar repository into a compact map of its identity, setup, entry points, structure, internal dependencies, application assembly, and change impact.

It runs locally and offline: no AI, no cloud service, and no repository upload. Results are based on repository evidence; unresolved information is not guessed.

## Why BriefLook?

Before changing an unfamiliar repository, developers usually need to answer two key questions:

1. **`brieflook .`** — *"How is this repository organized?"*
   Highlights language, framework, prerequisites, entry points, project structure, package dependencies, and container assembly.

2. **`brieflook impact <path>`** — *"What could be affected if I change this?"*
   Surfaces direct and transitive internal dependents derived from import relationships.

## Examples

### 1. Repository Scan (`brieflook .`)

```text
$ brieflook .

          Repository
+-----------------------------+
| Property        | Value     |
|-----------------+-----------|
| Name            | storefront|
| Language        | TypeScript|
| Framework       | React     |
+-----------------------------+

          Quick Start
+-----------------------------------------------+
| Prerequisite | Version | Reason               |
|--------------+---------+----------------------|
| Node.js      | >=20    | Defined in package…  |
+-----------------------------------------------+

                 Entry Points
+--------------------------------------------+
| # | Path               | Reason              |
|---+--------------------+---------------------|
| 1 | src/main.tsx       | React bootstrap.    |
+--------------------------------------------+

          Run Guide
+---------------------------+
| Step    | Command         |
|---------+-----------------|
| Install | pnpm install    |
| Run     | pnpm dev        |
| Test    | pnpm test       |
+---------------------------+

      Module Dependencies
+-------------------------------+
| Package     | Depends On      |
|-------------+-----------------|
| apps/web    | packages/ui     |
| apps/api    | packages/db     |
+-------------------------------+

     Application Assembly
+-----------------------------------------+
| Component | Kind    | Ports | Depends On|
|-----------+---------+-------+-----------|
| api       | compose | 8080  | db        |
| db        | compose | 5432  | -         |
+-----------------------------------------+
```

### 2. Change & Impact Analysis (`brieflook impact <path>`)

```text
$ brieflook impact src/core/engine.py --include-tests

             Potential Impact
+----------------------------------------+
| Property | Value                       |
|----------+-----------------------------|
| Target   | src/core/engine.py          |
+----------------------------------------+

Direct Dependents
  src/api/routes.py
  src/cli/main.py

Transitive Dependents
  src/app.py

Test Impact
  tests/test_engine.py
```

## What BriefLook Tells You

| Capability | Onboarding / Change-management question it answers |
|---|---|
| Repository Identity | What project, language, framework, and package manager is this? |
| Quick Start | What prerequisites are needed? |
| Environment Setup | Which environment variables and setup files are present? |
| Start Here | Which documentation and configuration files should I read first? |
| Entry Points | Where can execution begin? |
| Run Guide | How can I install, run, and test the project? |
| Project Structure | Which directories make up the repository? |
| Workspace Detection | Which packages belong to an explicitly declared workspace? |
| Module Dependencies | Which internal architectural boundaries depend on others? |
| Circular Package Dependencies | Which package boundaries form a strongly connected group? |
| Application Assembly | How do services, ports, and containers assemble from Compose/Docker declarations? |
| Change & Impact Intelligence | What files may be affected by changing this file or directory based on import relationships? |

## Install

```bash
pip install brieflook
```

Or install as a `uv` tool:

```bash
uv tool install brieflook
```

## Usage

```bash
# Scan repository organization
brieflook .
brieflook /path/to/repository

# Analyze potential change impact
brieflook impact src/brieflook/core/index.py
brieflook impact src/brieflook/core/index.py --include-tests
brieflook impact D:\path\to\repository\src\some_file.py

# Show installed version
brieflook --version
```

## Change & Impact Intelligence

`brieflook impact <path>` answers: *"If I change this file or directory, which other files could be affected?"*

- **Evidence-based:** Reports potential impact derived strictly from repository import relationships. It does **not** predict guaranteed breakage, semantic failure, or runtime bugs.
- **Direct & Transitive:** Surfaces direct dependents (modules that import the target) and transitive dependents (modules that import direct dependents).
- **Test Impact:** Separates production code from test files. Use `--include-tests` to show test dependents.
- **Circular Groups:** Displays a warning if the target module belongs to a circular dependency group.
- **Target Resolution:** Supports repository-relative paths (`src/foo.py`, `src\foo.py`) and absolute paths (`D:\path\to\repo\src\foo.py`).

## Application Assembly

BriefLook analyzes explicitly declared Docker Compose (`compose.yaml`, `docker-compose.yml`) and Dockerfile configuration to surface multi-container deployment architecture:

- **Compose Analysis:** Detects services, `image`, `build` context, host/container `ports`, service relationships (`depends_on`), `command`/`entrypoint`, environment variable names, and `env_file`.
- **Dockerfile Analysis:** Detects base images (`FROM`), exposed ports (`EXPOSE`), `CMD`, and `ENTRYPOINT`.
- **Run Guide Integration:** Adds `docker compose up` to the Run Guide when root Compose declarations exist.

*Note:* BriefLook reports declared repository assembly evidence. It does **not** inspect runtime container state, Kubernetes clusters, live health, port conflicts, or runtime variable values.

## Import Intelligence (Python, JS/TS)

BriefLook builds a language-agnostic `ImportGraph` for Python and JavaScript/TypeScript:

- **Python:** Analyzes imports using Python's AST. Supports absolute and relative imports, `src/` layouts, and package aggregation.
- **JavaScript & TypeScript:** Supports `.js`, `.jsx`, `.ts`, `.tsx`, ES imports, CommonJS `require()`, dynamic `import()`, relative paths, `index.*` resolution, and `tsconfig.json`/`jsconfig.json` path aliases.

External dependencies (e.g., `react`, `express`, `pytest`) are excluded. Unresolved imports are ignored rather than guessed.

## Dependency Boundaries

Module Dependencies are aggregated at architectural boundaries rather than arbitrary source folders:

- Declared workspace packages are the strongest boundary evidence.
- Nested `package.json` directories can establish independent package boundaries.
- Declared source roots (or a real `src/` directory) establish application boundaries.
- Imports within the same boundary are omitted from package dependency tables to avoid clutter.

## Workspace and Monorepo Support

BriefLook recognizes explicitly declared workspaces from repository-root manifests for **pnpm**, **npm**, **Yarn**, **Bun**, **uv**, **Cargo**, and **Go**. Workspaces are recognized only when declarations exist at the root.

## Evidence over Guessing

```text
Repository evidence
        ↓
Deterministic analysis
        ↓
Reported result
```

BriefLook avoids AI-generated claims, guessed dependencies, and cloud uploads. The core principle is **useful over impressive**: show proven information, or show less.

## Current Status

**Current release: v0.5.0**

v0.5.0 includes repository onboarding analysis, workspace detection, Python and JavaScript/TypeScript import intelligence, package dependency analysis, circular package dependency detection, Docker Compose / Dockerfile application assembly, and change & impact analysis.

## Roadmap

### Next — Public API Surface

- Public exports and exported modules
- Package export surfaces and public interfaces

### Future — Change & Impact Intelligence Expansion

- Richer package-level impact views
- Dependency path chains
- Machine-readable output formats (e.g., JSON)

*The roadmap evolves based on real developer feedback.*

## Feedback and Contributing

Scanned a repository, investigated a change, and still had to manually search for something?

**Tell us what BriefLook missed.** Open a GitHub issue or discussion with this detail:

> I scanned this repository, but I still had to manually search for ______.

To work on BriefLook locally:

```bash
git clone https://github.com/nabilkhan-01/brieflook.git
cd brieflook
uv sync
uv run brieflook .
uv run pytest
```

## License

MIT License.
