Metadata-Version: 2.5
Name: brieflook
Version: 0.6.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 three 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.

3. **`brieflook api [path]`** — *"What does this repository expose for other code to use, and where is that interface declared?"*
   Reports statically discoverable public API surfaces, explicit exports, package re-exports, and manifest entry points.

## 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
```

### 3. Public API Surface Intelligence (`brieflook api [path]`)

```text
$ brieflook api .

    Public API Surface
+------------------------+
| Property   | Value     |
|------------+-----------|
| Repository | my-library|
+------------------------+

Python

Explicit Exports (__all__)
  src/my_package/__init__.py
    Client (line 8)
    create_client (line 9)

Package Re-exports (__init__.py imports)
  src/my_package/__init__.py
    models.User -> my_package.models.User (line 4)

JavaScript / TypeScript

Source Exports
  src/index.ts
    Client (class, line 12)
    createClient (function, line 25)
    default (default export, line 40)
    ClientConfig (interface, line 5)

Package Entry Points (package.json)
  package.json
    main: ./dist/index.js
    types: ./dist/index.d.ts
    . -> ./dist/index.js
    ./utils -> ./dist/utils.js

                 Summary
+---------------------------------------+
| Category                      | Count |
|-------------------------------+-------|
| Explicit exports (__all__)    |     2 |
| Package re-exports            |     1 |
| Inferred public definitions   |     0 |
| JavaScript/TypeScript exports |     4 |
| Declared package entry points |     4 |
+---------------------------------------+
```

## What BriefLook Tells You

| Capability | Onboarding / Change-management question it answers |
|---|---|
| Public API Surface Intelligence | What does this repository expose for other code to use, and where is that interface declared? |
| 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

# Discover public API surface
brieflook api .
brieflook api src/brieflook

# 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
```

## Public API Surface Intelligence

`brieflook api [path]` answers: *"What does this repository expose for other code to use, and where is that interface declared?"*

It inspects source files and package manifests to report statically discoverable public interfaces without executing repository code or calling external networks.

### Supported Declarations

#### Python
- **Explicit exports:** Identifies `__all__` lists and tuples of strings (including augmented assignments `__all__ += [...]`) in modules and `__init__.py`.
- **Package re-exports:** Discovers re-exports declared through package `__init__.py` files, such as `from .sub import Item`, `from .sub import Internal as Public`, and `from . import module`.
- **Inferred public-looking definitions:** For modules without an explicit `__all__`, identifies top-level non-private (`non-_`) functions, classes, and constants.

#### JavaScript & TypeScript
- **Source exports:** Named declarations (`const`, `let`, `var`, `function`, `async function`, `class`, `interface`, `type`, `enum`), default exports, explicit export clauses (`export { ... }`), and type exports (`export type { ... }`).
- **Re-exports:** Re-exports using `export { ... } from`, and wildcard re-exports (`export * from`, `export * as ns from`).
- **Package entry points:** Inspects `package.json` for entry points (`main`, `module`, `types`, `typings`) and conditional `exports` maps (including nested condition trees such as `import`, `require`, `node`, `default`).

### Explicit Exports vs. Inferred Definitions

BriefLook strictly adheres to **Evidence over Guessing**:
- **Explicit exports** (`__all__`, `export`, manifest entry points) represent intentional public interface contracts committed by the author.
- **Inferred definitions** are non-private definitions identified by convention in modules that lack an explicit public contract. They are clearly labeled as inferred so developers know they are not guaranteed API contracts.

### Static Analysis Limitations

BriefLook runs entirely offline and statically:
- **Zero code execution:** It never executes `setup.py`, imports Python modules, runs TypeScript compilers, or invokes Node.js.
- **Dynamic exports disclosed:** If `__all__` is dynamically computed (e.g. `[name for name in dir()]` or function calls), or if syntax cannot be deterministically resolved, BriefLook reports an **Analysis Limitation** instead of guessing.

## 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.6.0 (Release Candidate) — Public API Surface Intelligence**

v0.6.0 introduces Public API Surface Intelligence (`brieflook api`), identifying statically declared public exports, package re-exports, inferred definitions, and manifest entry points across Python and JavaScript/TypeScript codebases.

## Roadmap

### Current Milestone — Public API Surface Intelligence (v0.6.0)

- Statically discoverable public exports (`__all__`, ES module exports)
- Package re-exports and subpath exports maps
- Distinguishing declared contracts from inferred naming conventions
- Analysis limitation reporting for dynamic exports

### Next — 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.
