brieflook 0.1.0__tar.gz

brieflook-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# ----------------------------
+# Python
+# ----------------------------
+__pycache__/
+*.py[cod]
+*.pyc
+
+# ----------------------------
+# Virtual environments
+# ----------------------------
+.venv/
+venv/
+
+# ----------------------------
+# Environment variables
+# ----------------------------
+.env
+.env.*
+!.env.example
+
+# ----------------------------
+# Test & quality tool caches
+# ----------------------------
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# ----------------------------
+# IDEs
+# ----------------------------
+.vscode/
+.idea/
+
+# ----------------------------
+# OS
+# ----------------------------
+.DS_Store
+Thumbs.db

brieflook-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Nabil Khan
+
+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.
+

brieflook-0.1.0/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: brieflook
+Version: 0.1.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
+
+> **Understand any repository in minutes.**
+
+brieflook is an open-source developer tool that helps you understand unfamiliar codebases faster.
+
+Instead of spending hours exploring folders, opening random files, and guessing where to start, brieflook analyzes a repository and provides a clear overview of its technologies, structure, and important entry points.
+
+Our goal is simple:
+
+> **Reduce repository onboarding from hours to minutes.**
+
+---
+
+## Status
+
+🚧 Early Development
+
+brieflook is under active development. The current focus is building a fast, reliable repository understanding engine before expanding into deeper repository analysis.
+
+---
+
+## Vision
+
+Every developer has experienced this moment:
+
+- You clone a new repository.
+- Hundreds of files appear.
+- You don't know where to begin.
+- You don't know which files matter.
+- You don't know how everything fits together.
+
+brieflook exists to remove that uncertainty.
+
+---
+
+## Project
+
+**Name:** brieflook
+
+**Tagline:** *Understand any repository in minutes.*
+
+**Started:** 2 August 2026
+
+---
+
+If brieflook saves you time understanding a repository, then it's doing exactly what it was built for.

brieflook-0.1.0/README.md

@@ -0,0 +1,47 @@
+# brieflook
+
+> **Understand any repository in minutes.**
+
+brieflook is an open-source developer tool that helps you understand unfamiliar codebases faster.
+
+Instead of spending hours exploring folders, opening random files, and guessing where to start, brieflook analyzes a repository and provides a clear overview of its technologies, structure, and important entry points.
+
+Our goal is simple:
+
+> **Reduce repository onboarding from hours to minutes.**
+
+---
+
+## Status
+
+🚧 Early Development
+
+brieflook is under active development. The current focus is building a fast, reliable repository understanding engine before expanding into deeper repository analysis.
+
+---
+
+## Vision
+
+Every developer has experienced this moment:
+
+- You clone a new repository.
+- Hundreds of files appear.
+- You don't know where to begin.
+- You don't know which files matter.
+- You don't know how everything fits together.
+
+brieflook exists to remove that uncertainty.
+
+---
+
+## Project
+
+**Name:** brieflook
+
+**Tagline:** *Understand any repository in minutes.*
+
+**Started:** 2 August 2026
+
+---
+
+If brieflook saves you time understanding a repository, then it's doing exactly what it was built for.

brieflook-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "brieflook"
+version = "0.1.0"
+description = "Understand any repository in minutes."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+
+keywords = [
+    "cli",
+    "repository",
+    "developer-tools",
+    "onboarding",
+    "codebase",
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Environment :: Console",
+]
+
+dependencies = [
+    "rich>=14.1.0",
+    "typer>=0.17.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/nabilkhan-01/brieflook"
+Repository = "https://github.com/nabilkhan-01/brieflook"
+Issues = "https://github.com/nabilkhan-01/brieflook/issues"
+
+[project.scripts]
+brieflook = "brieflook.cli.main:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.1",
+    "ruff>=0.12.8",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

brieflook-0.1.0/src/brieflook/__main__.py

@@ -0,0 +1,7 @@
+"""
+Application entry point.
+"""
+
+from brieflook.cli.main import app
+
+app()

brieflook-0.1.0/src/brieflook/cli/main.py

@@ -0,0 +1,140 @@
+"""
+CLI entry point for brieflook.
+
+Responsibilities:
+- Parse command-line arguments.
+- Invoke the appropriate application services.
+- Format and display results to the terminal.
+
+This module should never contain business logic.
+Repository analysis belongs in the core and project modules.
+"""
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from brieflook.project.detector import ProjectDetector
+from brieflook.guide.detector import GuideDetector
+from brieflook.entrypoints.detector import EntryPointDetector
+from brieflook.run.detector import RunGuideDetector
+from brieflook.structure.detector import ProjectStructureDetector
+from brieflook.core.index_builder import RepositoryIndexBuilder
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Understand any repository in minutes.",
+)
+
+console = Console()
+
+
+@app.command()
+def scan(
+    path: Path = typer.Argument(
+        Path("."),
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+        help="Path to the repository.",
+    ),
+) -> None:
+    """
+    Scan a repository.
+    """
+
+    detector = ProjectDetector()
+    project = detector.detect(path)
+
+    index = RepositoryIndexBuilder().build(path)
+
+    guide = GuideDetector().detect(index, project)
+
+    table = Table(title="Repository")
+
+    table.add_column("Property", style="cyan")
+    table.add_column("Value", style="green")
+
+    table.add_row("Name", path.name)
+    table.add_row("Language", project.language)
+    table.add_row("Framework", project.framework or "Unknown")
+    table.add_row("Package Manager", project.package_manager or "Unknown")
+    table.add_row("Project Type", project.project_type or "Unknown")
+
+    console.print(table)
+
+    console.print()
+
+    guide_table = Table(title="Start Here")
+
+    guide_table.add_column("#", style="cyan", justify="right")
+    guide_table.add_column("Path", style="green")
+    guide_table.add_column("Reason")
+
+    for i, item in enumerate(guide, start=1):
+        guide_table.add_row(
+            str(i), 
+            item.path, 
+            item.reason,
+        )
+
+    console.print(guide_table)
+
+    console.print()
+
+    entry_points = EntryPointDetector().detect(index)
+
+    entry_table = Table(title="Entry Points")
+
+    entry_table.add_column("#", style="cyan", justify="right")
+    entry_table.add_column("Path", style="green")
+    entry_table.add_column("Reason")
+
+    for i, ep in enumerate(entry_points, start=1):
+        entry_table.add_row(
+            str(i),
+            ep.path,
+            ep.reason,
+        )
+
+    console.print(entry_table)
+
+    console.print()
+
+    run_guide = RunGuideDetector().detect(project, index)
+
+    run_table = Table(title="Run Guide")
+
+    run_table.add_column("Step", style="cyan")
+    run_table.add_column("Command", style="green")
+
+    if run_guide.install_command:
+        run_table.add_row("Install", run_guide.install_command)
+    if run_guide.run_command:
+        run_table.add_row("Run", run_guide.run_command)
+    if run_guide.test_command:
+        run_table.add_row("Test", run_guide.test_command)
+
+    console.print(run_table)
+
+    console.print()
+
+    structure = ProjectStructureDetector().detect(index)
+
+    structure_table = Table(title="Project Structure")
+
+    structure_table.add_column("#", style="cyan", justify="right")
+    structure_table.add_column("Directory", style="green")
+    structure_table.add_column("Purpose")
+
+    for i, d in enumerate(structure, start=1):
+        structure_table.add_row(
+            str(i),
+            d.path,
+            d.reason,
+        )
+
+    console.print(structure_table)

brieflook-0.1.0/src/brieflook/core/index.py

@@ -0,0 +1,41 @@
+"""
+Repository index.
+
+Responsibilities:
+- Store an in-memory representation of a repository.
+- Provide fast filesystem lookups.
+- Avoid repeated filesystem traversal.
+
+This module should never:
+- Detect technologies.
+- Generate terminal output.
+- Contain business rules.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class RepositoryIndex:
+    """
+    Fast lookup structure for repository contents.
+    """
+
+    root: Path
+
+    files: dict[str, list[Path]]
+    directories: dict[str, list[Path]]
+    extensions: dict[str, list[Path]]
+
+    def find_file(self, filename: str) -> list[Path]:
+        """
+        Return every file with the given filename.
+        """
+        return self.files.get(filename, [])
+
+    def has_file(self, filename: str) -> bool:
+        """
+        Return True if the repository contains the file.
+        """
+        return filename in self.files

brieflook-0.1.0/src/brieflook/core/index_builder.py

@@ -0,0 +1,68 @@
+"""
+Repository index builder.
+
+Responsibilities:
+- Traverse the repository once.
+- Build a RepositoryIndex.
+- Normalize filesystem information.
+
+This module should never:
+- Detect technologies.
+- Rank files.
+- Produce CLI output.
+"""
+
+from collections import defaultdict
+from pathlib import Path
+
+from brieflook.core.index import RepositoryIndex
+
+
+IGNORED_DIRECTORIES = {
+    ".git",
+    ".venv",
+    "__pycache__",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".mypy_cache",
+    ".idea",
+    ".vscode",
+    "node_modules",
+    "dist",
+    "build",
+}
+
+
+class RepositoryIndexBuilder:
+    """
+    Builds a RepositoryIndex by traversing the repository once.
+    """
+
+    def build(self, root: Path) -> RepositoryIndex:
+
+        files: dict[str, list[Path]] = defaultdict(list)
+        directories: dict[str, list[Path]] = defaultdict(list)
+        extensions: dict[str, list[Path]] = defaultdict(list)
+
+        for item in root.rglob("*"):
+
+            if any(part in IGNORED_DIRECTORIES for part in item.parts):
+                continue
+
+            if item.is_file():
+
+                files[item.name].append(item)
+
+                if item.suffix:
+                    extensions[item.suffix].append(item)
+
+            elif item.is_dir():
+
+                directories[item.name].append(item)
+
+        return RepositoryIndex(
+            root=root,
+            files=dict(files),
+            directories=dict(directories),
+            extensions=dict(extensions),
+        )

brieflook-0.1.0/src/brieflook/core/repository.py

@@ -0,0 +1,38 @@
+"""
+Repository domain models.
+
+This module defines the core data structures shared across brieflook.
+
+These models represent facts about a repository without making
+assumptions or interpretations.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(slots=True)
+class RepositoryFacts:
+    """
+    Raw facts collected from a repository.
+
+    Responsibilities:
+    - Store filesystem facts.
+    - Represent the current state of a repository.
+    - Serve as input for higher-level analysis.
+
+    This class should never:
+    - Detect frameworks.
+    - Infer project types.
+    - Perform filesystem scanning.
+    - Contain business logic.
+    """
+
+    name: str
+    root: Path
+
+    file_count: int
+    directory_count: int
+
+    has_git: bool
+    has_readme: bool

brieflook-0.1.0/src/brieflook/entrypoints/__init__.py

@@ -0,0 +1,2 @@
+
+

brieflook-0.1.0/src/brieflook/entrypoints/detector.py

@@ -0,0 +1,137 @@
+"""
+Application entry point detection.
+
+Responsibilities:
+- Identify real application entry points from the repository index.
+- Provide a reason for each detected entry point.
+
+This module should never:
+- Traverse the filesystem.
+- Generate terminal output.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from brieflook.core.index import RepositoryIndex
+from brieflook.entrypoints.models import EntryPoint
+
+
+@dataclass(frozen=True, slots=True)
+class _Rule:
+    filename: str
+    reason: str
+    root_only: bool = False
+
+
+_RULES: list[_Rule] = [
+    # Python
+    _Rule("__main__.py", "Python package entry point."),
+    _Rule("main.py", "Python application entry point.", root_only=True),
+    _Rule("manage.py", "Django management entry point."),
+    _Rule("app.py", "Python application entry point.", root_only=True),
+    _Rule("wsgi.py", "WSGI application entry point."),
+    _Rule("asgi.py", "ASGI application entry point."),
+
+    # JavaScript / TypeScript
+    _Rule("server.js", "Node.js server entry point."),
+    _Rule("index.js", "JavaScript application entry point."),
+    _Rule("main.js", "JavaScript application entry point."),
+
+    # Next.js
+    _Rule("page.tsx", "Next.js application entry point."),
+
+    # Rust
+    _Rule("main.rs", "Rust application entry point."),
+
+    # Java
+    _Rule("Application.java", "Java application entry point."),
+    _Rule("Main.java", "Java application entry point."),
+]
+
+# JS/TS files that are only valid inside a src/ directory.
+_SRC_ONLY = {"main.ts", "main.tsx", "index.ts", "index.tsx", "main.js", "main.jsx", "index.js", "index.jsx"}
+
+# Next.js page files and the directories they must live under.
+_NEXTJS_DIRS = {"page.tsx": {"app", "pages"}}
+
+# Next.js pages/index.tsx pattern.
+_PAGES_INDEX = "index.tsx"
+
+# Go entry point pattern: main.go inside a cmd/ tree.
+_GO_ENTRY = "main.go"
+
+
+class EntryPointDetector:
+    """
+    Detect application entry points from a RepositoryIndex.
+    """
+
+    def detect(self, index: RepositoryIndex) -> list[EntryPoint]:
+        results: list[EntryPoint] = []
+
+        for rule in _RULES:
+            matches = index.find_file(rule.filename)
+            for file_path in matches:
+                if self._matches_rule(rule, file_path, index.root):
+                    rel = file_path.relative_to(index.root).as_posix()
+                    results.append(EntryPoint(path=rel, reason=rule.reason))
+
+        # src-only JS/TS files
+        for filename in sorted(_SRC_ONLY):
+            for file_path in index.find_file(filename):
+                if self._is_in_src(file_path, index.root):
+                    rel = file_path.relative_to(index.root).as_posix()
+                    reason = self._js_ts_reason(filename)
+                    results.append(EntryPoint(path=rel, reason=reason))
+
+        # Next.js pages/index.tsx
+        for file_path in index.find_file(_PAGES_INDEX):
+            if self._is_nextjs_pages_index(file_path):
+                rel = file_path.relative_to(index.root).as_posix()
+                results.append(EntryPoint(path=rel, reason="Next.js pages entry point."))
+
+        # Go cmd/**/main.go
+        for file_path in index.find_file(_GO_ENTRY):
+            if self._is_go_cmd_entry(file_path):
+                rel = file_path.relative_to(index.root).as_posix()
+                results.append(EntryPoint(path=rel, reason="Go application entry point."))
+
+        return results
+
+    def _matches_rule(self, rule: _Rule, file_path: Path, root: Path) -> bool:
+        if rule.root_only:
+            return file_path.parent == root
+
+        # Next.js page.tsx must be inside app/ directory.
+        if rule.filename in _NEXTJS_DIRS:
+            return self._is_in_nextjs_dir(rule.filename, file_path)
+
+        # Rust main.rs must be inside src/ directory.
+        if rule.filename == "main.rs":
+            return self._is_in_src(file_path, root)
+
+        return True
+
+    def _is_in_src(self, file_path: Path, root: Path) -> bool:
+        rel = file_path.relative_to(root)
+        return "src" in rel.parent.parts
+
+    def _is_in_nextjs_dir(self, filename: str, file_path: Path) -> bool:
+        valid_dirs = _NEXTJS_DIRS[filename]
+        return any(part in valid_dirs for part in file_path.parts)
+
+    def _is_nextjs_pages_index(self, file_path: Path) -> bool:
+        parts = file_path.parts
+        return "pages" in parts
+
+    def _is_go_cmd_entry(self, file_path: Path) -> bool:
+        return "cmd" in file_path.parts
+
+    def _js_ts_reason(self, filename: str) -> str:
+        if filename.endswith((".tsx", ".jsx")):
+            return "React application bootstrap."
+        if filename.endswith(".ts"):
+            return "TypeScript application entry point."
+        return "JavaScript application entry point."
+

brieflook-0.1.0/src/brieflook/entrypoints/models.py

@@ -0,0 +1,16 @@
+"""
+Entry point models.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class EntryPoint:
+    """
+    A detected application entry point.
+    """
+
+    path: str
+    reason: str
+