Metadata-Version: 2.4
Name: brieflook
Version: 0.3.1
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)

> 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, and internal dependencies.

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 manually find:

- What kind of project is this?
- What is required to run it?
- Where should I start reading?
- Where does execution begin?
- How do internal packages connect, and are any circularly coupled?

BriefLook performs this initial inspection in one command.

## Example

```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 | npm install     |
| Run     | npm run dev     |
| Test    | npm test        |
+---------------------------+

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

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

      Circular Package Dependencies
+-------------------------------------------+
| Coupled Package Group                     |
|-------------------------------------------|
| packages/auth, packages/session           |
+-------------------------------------------+
```

The scan is intentionally compact: it highlights onboarding facts and proven relationships rather than printing every file import.

## What BriefLook Tells You

| Capability | Onboarding 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? |

## Install

```bash
pip install brieflook
```

Or install it as a uv tool:

```bash
uv tool install brieflook
```

## Usage

```bash
# Scan the current directory
brieflook .

# Scan another repository
brieflook /path/to/repository

# Show the installed version
brieflook --version
```

## What Is Currently Supported

BriefLook detects repository identity, prerequisites, environment setup, start-here files, entry points, run commands, project structure, explicit workspaces, and internal package dependencies.

Import intelligence currently supports Python, JavaScript, and TypeScript source files. It reports package-level relationships and compact circular package groups when repository evidence proves them.

## Python Import Intelligence

For Python repositories, BriefLook analyzes imports using Python's AST and reports internal module relationships at package level. It supports absolute and relative imports, `src/` layouts, and circular dependency detection.

External imports are not included in Module Dependencies.

## JavaScript / TypeScript Import Intelligence

For JavaScript and TypeScript repositories, BriefLook supports:

- `.js`, `.jsx`, `.ts`, and `.tsx` files
- ES module imports, including default, named, namespace, and side-effect imports
- CommonJS `require()` and dynamic `import()`
- Relative imports, explicit extensions, and `index.*` resolution
- Explicit `tsconfig.json` and `jsconfig.json` path aliases

Only imports that resolve to actual repository files become internal graph relationships. External packages such as `react`, `express`, and `axios` are excluded. Unresolved imports are ignored rather than guessed.

BriefLook does not provide full TypeScript compiler semantics or bundler/plugin resolution.

## Dependency Boundaries

Module Dependencies are aggregated at architectural boundaries, not arbitrary source folders.

- Declared workspace packages are the strongest boundary evidence.
- Nested `package.json` directories can establish independent package boundaries.
- Declared source roots from configuration, or a real `src/` directory, can establish an application boundary.

Imports within the same boundary are omitted from the default table. For example, an import from `src/pages/` to `src/components/` does not create a pseudo-package dependency.

If BriefLook cannot establish a boundary from repository evidence, it prefers reporting fewer relationships over inventing one.

This keeps the default dependency view short enough to inspect in a normal terminal.

It also keeps raw file-level structure available in the repository rather than relabeling it as architecture.

The result is a compact starting point for repository onboarding.

## Workspace and Monorepo Support

BriefLook recognizes explicitly declared workspaces from repository-root manifests for:

- pnpm
- npm, Yarn, and Bun
- uv
- Cargo
- Go

It only treats a repository as a workspace when that declaration is present at the root. Directories named `apps/` or `packages/` are not considered workspace packages by name alone.

Declared workspace packages can appear in Project Structure and act as dependency boundaries when imports actually connect them.

## Evidence over Guessing

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

BriefLook deliberately avoids:

- AI-generated architecture claims
- Guessed dependencies or invented entry points
- Treating arbitrary directories as workspaces or packages
- Cloud analysis and repository uploads

The goal is useful over impressive: show proven information, or show less.

## Current Status

**Current release: v0.3.0**

v0.3.0 includes repository onboarding analysis, explicit workspace detection, Python and JavaScript/TypeScript ImportGraph support, package-level Module Dependencies, and SCC-based Circular Package Dependencies.

## Roadmap

### v0.4 — Application Surface Intelligence

- HTTP routes
- CLI commands
- Application-facing entry surfaces
- Relationships to internal modules

### v0.5 — Public API Surface

- Public exports
- Exported modules
- Package exports
- Public interfaces

### Future: Change & Impact Intelligence

> If I change this module, what else could be affected?

The roadmap will evolve based on real developer feedback.

## Feedback and Contributing

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

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

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

BriefLook is intended as a fast first pass before making changes.

Use its output to focus your reading, then verify details in the repository itself.

It does not replace repository-specific review or engineering judgment.

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.
