repoglance 0.2.1__tar.gz

repoglance-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install -e ".[dev]"
+      - name: Test
+        run: python -m pytest -q
+      - name: Smoke test the CLI
+        run: repoglance --json .

repoglance-0.2.1/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+
+# Publishes to PyPI when a version tag (v*) is pushed, using PyPI's
+# trusted-publisher (OIDC) flow — no API token stored in the repo.
+#
+# One-time setup on PyPI: create the project's "pending publisher" at
+# https://pypi.org/manage/account/publishing/ with
+#   owner: SRJ-ai   repo: repolens   workflow: release.yml   environment: pypi
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Check metadata
+        run: |
+          python -m pip install --upgrade twine
+          twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    # Enable by setting repo variable PUBLISH_TO_PYPI=true after the PyPI
+    # pending publisher is configured (see RELEASING.md). Until then, tags can
+    # be cut (e.g. for the Marketplace) without a failing publish job.
+    if: ${{ vars.PUBLISH_TO_PYPI == 'true' }}
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write        # required for trusted publishing (OIDC)
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

repoglance-0.2.1/.github/workflows/repoglance.yml

@@ -0,0 +1,25 @@
+name: repoglance
+
+# Dogfoods the action: on every PR, post a repoglance report and enforce a
+# minimum health score.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: ./
+        with:
+          fail-under: "55"
+          max-complexity: "30"

repoglance-0.2.1/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db

repoglance-0.2.1/.pre-commit-hooks.yaml

@@ -0,0 +1,8 @@
+- id: repoglance
+  name: repoglance health gate
+  description: "Analyze the repo and fail if the health score drops below a threshold."
+  entry: repoglance
+  args: ["--ci", "--fail-under", "70"]
+  language: python
+  pass_filenames: false
+  always_run: true

repoglance-0.2.1/.repolens-badge.json

@@ -0,0 +1 @@
+{"schemaVersion": 1, "label": "repoglance", "message": "1.4k loc \u2022 Python", "color": "blue"}

repoglance-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to repoglance
+
+Thanks for helping! repoglance aims to stay **small, fast, and dependency-light**.
+
+## Dev setup
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest -q
+```
+
+## Adding a language
+
+Most language support is a one-line change. Add the extension to `EXT_LANG` in
+[`src/repoglance/languages.py`](src/repoglance/languages.py):
+
+```python
+"kt": "Kotlin",
+```
+
+Optionally give it a color in `LANG_COLOR` and a comment prefix in
+`_COMMENT_PREFIX` (in `scanner.py`) so blank/comment/code counts are accurate.
+
+## Guidelines
+
+- Keep the runtime dependencies to `rich` + `click`. Anything heavier needs a
+  strong justification.
+- Every behavior the report shows must also be reachable via `--json`.
+- Add or update a test in `tests/` for any logic change.
+- Run `python -m pytest -q` before opening a PR.
+
+## Ideas / good first issues
+
+- SVG or PNG report export.
+- Per-directory rollups.
+- `--since <rev>` to scope git activity to a range.
+- More accurate multi-line comment handling.
+
+PRs and issues welcome. Be kind. 🌱

repoglance-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 repoglance contributors
+
+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.

repoglance-0.2.1/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: repoglance
+Version: 0.2.1
+Summary: Instant, gorgeous insight into any code repository — languages, complexity hotspots, TODOs and git activity in one terminal command.
+Project-URL: Homepage, https://github.com/SRJ-ai/repolens
+Project-URL: Repository, https://github.com/SRJ-ai/repolens
+Project-URL: Issues, https://github.com/SRJ-ai/repolens/issues
+Author: repoglance contributors
+License: MIT
+License-File: LICENSE
+Keywords: cli,cloc,code-analysis,complexity,developer-tools,git,loc,rich,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 🔍 repoglance
+
+### Instant, gorgeous insight into any code repository — in one command.
+
+Point it at any folder. In under a second you get a beautiful terminal report:
+language breakdown, complexity hotspots, TODO tracker, biggest files, and git
+activity. **Zero config. Zero API keys. Zero telemetry.**
+
+[![CI](https://github.com/SRJ-ai/repolens/actions/workflows/ci.yml/badge.svg)](https://github.com/SRJ-ai/repolens/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+[![repoglance](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/SRJ-ai/repolens/main/.repolens-badge.json)](https://github.com/SRJ-ai/repolens)
+
+</div>
+
+---
+
+## Why repoglance?
+
+You clone an unfamiliar repo. What *is* this thing? How big? What's the messy
+part? Where's the unfinished work? `cloc` gives you a wall of numbers. `tokei`
+is fast but bare. `repoglance` answers the human questions in one glance:
+
+```bash
+repoglance .
+```
+
+<div align="center">
+
+![repoglance demo](assets/demo.svg)
+
+</div>
+
+## Seen in the wild
+
+repoglance run against well-known projects (click to view the full report):
+
+| Project | Files | Lines of code | Health |
+|---|--:|--:|:--:|
+| [flask](assets/showcase/flask.svg) | 200 | 25,030 | D (64) |
+| [httpie](assets/showcase/httpie.svg) | 217 | 19,604 | D (62) |
+| [requests](assets/showcase/requests.svg) | 71 | 13,215 | D (69) |
+
+<div align="center">
+
+[![flask report](assets/showcase/flask.svg)](assets/showcase/flask.svg)
+
+</div>
+
+## Install
+
+```bash
+pip install repoglance
+```
+
+Or run without installing:
+
+```bash
+pipx run repoglance .
+```
+
+## Usage
+
+```bash
+repoglance                       # analyze current directory
+repoglance path/to/repo          # analyze another repo
+repoglance --json                # machine-readable output for scripts / CI
+repoglance --svg report.svg      # export a vector report
+repoglance --html report.html    # export a browser report
+repoglance --badge badge.svg     # export an embeddable badge
+repoglance --ci --max-complexity 25   # fail CI on hotspots
+repoglance --no-git              # skip git history
+repoglance --ignore dist --ignore fixtures
+```
+
+### JSON output
+
+Pipe structured data anywhere — dashboards, CI gates, badges:
+
+```bash
+repoglance --json | jq '.languages.Python.code'
+```
+
+## What it measures
+
+| Section | What you get |
+|---|---|
+| **Languages** | Lines of code per language, ranked, with % bars |
+| **Complexity hotspots** | Per-function cyclomatic complexity (Python via AST; heuristic for other langs) |
+| **TODO tracker** | Every `TODO` / `FIXME` / `HACK` / `XXX` / `BUG` with file:line |
+| **Biggest files** | The files most likely to need splitting |
+| **Git activity** | Top authors, most-churned files, active days, project lifespan |
+
+Binary files, `node_modules`, `.venv`, build dirs and friends are skipped
+automatically.
+
+## More than a counter
+
+`repoglance` isn't just another `cloc`. Tools like `tokei`, `cloc` and `scc`
+answer *"how many lines?"*. repoglance answers *"what should I look at?"* — and
+gives you artifacts you can put in a PR or a README.
+
+| | repoglance | tokei | scc | cloc |
+|---|:---:|:---:|:---:|:---:|
+| Lines-of-code by language | ✅ | ✅ | ✅ | ✅ |
+| Complexity hotspots (per function) | ✅ | ❌ | ⚠️ file-level | ❌ |
+| TODO / FIXME tracker | ✅ | ❌ | ❌ | ❌ |
+| Git activity (authors, churn) | ✅ | ❌ | ❌ | ❌ |
+| JSON output | ✅ | ✅ | ✅ | ✅ |
+| **HTML / SVG report export** | ✅ | ❌ | ❌ | ❌ |
+| **Embeddable repo badge** | ✅ | ❌ | ❌ | ❌ |
+| **CI gate (`--max-complexity`)** | ✅ | ❌ | ❌ | ❌ |
+| Zero install deps beyond one `pip` | ✅ | (binary) | (binary) | (perl) |
+
+## Share it: badges & reports
+
+Generate a self-contained SVG badge — no shields.io round-trip, no tracking:
+
+```bash
+repoglance --badge assets/badge.svg
+```
+
+![repoglance badge](assets/badge.svg)
+
+Export the full report as a standalone file to drop in a PR or wiki:
+
+```bash
+repoglance --svg report.svg      # vector, pixel-perfect
+repoglance --html report.html    # opens in any browser
+```
+
+## Guard your codebase in CI
+
+Fail the build when complexity or TODO debt crosses a line:
+
+```bash
+repoglance --ci --max-complexity 25 --max-todos 100
+```
+
+```yaml
+# .github/workflows/quality.yml
+- run: pip install repoglance
+- run: repoglance --ci --max-complexity 25
+```
+
+Exit code `0` = clean, `2` = a threshold was exceeded.
+
+## Integrations
+
+### GitHub Action — comment on every PR
+
+Drop repoglance into any repo. It posts a sticky report comment on pull requests
+and can gate the build:
+
+```yaml
+# .github/workflows/repoglance.yml
+name: repoglance
+on: [pull_request]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: SRJ-ai/repolens@main
+        with:
+          fail-under: "70"       # optional health gate
+          max-complexity: "25"   # optional complexity gate
+```
+
+The report also lands in the workflow's **job summary** every run.
+
+### pre-commit hook
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/SRJ-ai/repolens
+    rev: v0.2.0
+    hooks:
+      - id: repoglance
+        args: ["--ci", "--fail-under", "70"]
+```
+
+### Self-updating badge
+
+Commit a shields endpoint file and point a dynamic badge at it — the badge
+refreshes itself, no service to run:
+
+```bash
+repoglance --badge-json .repolens-badge.json   # commit this file
+```
+
+```markdown
+![repoglance](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/SRJ-ai/repolens/main/.repolens-badge.json)
+```
+
+### Markdown anywhere
+
+```bash
+repoglance --md   # paste into a PR, wiki, or Slack
+```
+
+## Design goals
+
+- **Fast** — a single `os.walk`, no external services.
+- **Honest** — no network, no telemetry, no surprise writes.
+- **Pretty** — powered by [rich](https://github.com/Textualize/rich).
+- **Scriptable** — everything the report shows is available as `--json`.
+
+## Contributing
+
+Adding a language is a one-line change in `languages.py`. PRs welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © repoglance contributors

repoglance-0.2.1/README.md

@@ -0,0 +1,223 @@
+<div align="center">
+
+# 🔍 repoglance
+
+### Instant, gorgeous insight into any code repository — in one command.
+
+Point it at any folder. In under a second you get a beautiful terminal report:
+language breakdown, complexity hotspots, TODO tracker, biggest files, and git
+activity. **Zero config. Zero API keys. Zero telemetry.**
+
+[![CI](https://github.com/SRJ-ai/repolens/actions/workflows/ci.yml/badge.svg)](https://github.com/SRJ-ai/repolens/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+[![repoglance](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/SRJ-ai/repolens/main/.repolens-badge.json)](https://github.com/SRJ-ai/repolens)
+
+</div>
+
+---
+
+## Why repoglance?
+
+You clone an unfamiliar repo. What *is* this thing? How big? What's the messy
+part? Where's the unfinished work? `cloc` gives you a wall of numbers. `tokei`
+is fast but bare. `repoglance` answers the human questions in one glance:
+
+```bash
+repoglance .
+```
+
+<div align="center">
+
+![repoglance demo](assets/demo.svg)
+
+</div>
+
+## Seen in the wild
+
+repoglance run against well-known projects (click to view the full report):
+
+| Project | Files | Lines of code | Health |
+|---|--:|--:|:--:|
+| [flask](assets/showcase/flask.svg) | 200 | 25,030 | D (64) |
+| [httpie](assets/showcase/httpie.svg) | 217 | 19,604 | D (62) |
+| [requests](assets/showcase/requests.svg) | 71 | 13,215 | D (69) |
+
+<div align="center">
+
+[![flask report](assets/showcase/flask.svg)](assets/showcase/flask.svg)
+
+</div>
+
+## Install
+
+```bash
+pip install repoglance
+```
+
+Or run without installing:
+
+```bash
+pipx run repoglance .
+```
+
+## Usage
+
+```bash
+repoglance                       # analyze current directory
+repoglance path/to/repo          # analyze another repo
+repoglance --json                # machine-readable output for scripts / CI
+repoglance --svg report.svg      # export a vector report
+repoglance --html report.html    # export a browser report
+repoglance --badge badge.svg     # export an embeddable badge
+repoglance --ci --max-complexity 25   # fail CI on hotspots
+repoglance --no-git              # skip git history
+repoglance --ignore dist --ignore fixtures
+```
+
+### JSON output
+
+Pipe structured data anywhere — dashboards, CI gates, badges:
+
+```bash
+repoglance --json | jq '.languages.Python.code'
+```
+
+## What it measures
+
+| Section | What you get |
+|---|---|
+| **Languages** | Lines of code per language, ranked, with % bars |
+| **Complexity hotspots** | Per-function cyclomatic complexity (Python via AST; heuristic for other langs) |
+| **TODO tracker** | Every `TODO` / `FIXME` / `HACK` / `XXX` / `BUG` with file:line |
+| **Biggest files** | The files most likely to need splitting |
+| **Git activity** | Top authors, most-churned files, active days, project lifespan |
+
+Binary files, `node_modules`, `.venv`, build dirs and friends are skipped
+automatically.
+
+## More than a counter
+
+`repoglance` isn't just another `cloc`. Tools like `tokei`, `cloc` and `scc`
+answer *"how many lines?"*. repoglance answers *"what should I look at?"* — and
+gives you artifacts you can put in a PR or a README.
+
+| | repoglance | tokei | scc | cloc |
+|---|:---:|:---:|:---:|:---:|
+| Lines-of-code by language | ✅ | ✅ | ✅ | ✅ |
+| Complexity hotspots (per function) | ✅ | ❌ | ⚠️ file-level | ❌ |
+| TODO / FIXME tracker | ✅ | ❌ | ❌ | ❌ |
+| Git activity (authors, churn) | ✅ | ❌ | ❌ | ❌ |
+| JSON output | ✅ | ✅ | ✅ | ✅ |
+| **HTML / SVG report export** | ✅ | ❌ | ❌ | ❌ |
+| **Embeddable repo badge** | ✅ | ❌ | ❌ | ❌ |
+| **CI gate (`--max-complexity`)** | ✅ | ❌ | ❌ | ❌ |
+| Zero install deps beyond one `pip` | ✅ | (binary) | (binary) | (perl) |
+
+## Share it: badges & reports
+
+Generate a self-contained SVG badge — no shields.io round-trip, no tracking:
+
+```bash
+repoglance --badge assets/badge.svg
+```
+
+![repoglance badge](assets/badge.svg)
+
+Export the full report as a standalone file to drop in a PR or wiki:
+
+```bash
+repoglance --svg report.svg      # vector, pixel-perfect
+repoglance --html report.html    # opens in any browser
+```
+
+## Guard your codebase in CI
+
+Fail the build when complexity or TODO debt crosses a line:
+
+```bash
+repoglance --ci --max-complexity 25 --max-todos 100
+```
+
+```yaml
+# .github/workflows/quality.yml
+- run: pip install repoglance
+- run: repoglance --ci --max-complexity 25
+```
+
+Exit code `0` = clean, `2` = a threshold was exceeded.
+
+## Integrations
+
+### GitHub Action — comment on every PR
+
+Drop repoglance into any repo. It posts a sticky report comment on pull requests
+and can gate the build:
+
+```yaml
+# .github/workflows/repoglance.yml
+name: repoglance
+on: [pull_request]
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: SRJ-ai/repolens@main
+        with:
+          fail-under: "70"       # optional health gate
+          max-complexity: "25"   # optional complexity gate
+```
+
+The report also lands in the workflow's **job summary** every run.
+
+### pre-commit hook
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/SRJ-ai/repolens
+    rev: v0.2.0
+    hooks:
+      - id: repoglance
+        args: ["--ci", "--fail-under", "70"]
+```
+
+### Self-updating badge
+
+Commit a shields endpoint file and point a dynamic badge at it — the badge
+refreshes itself, no service to run:
+
+```bash
+repoglance --badge-json .repolens-badge.json   # commit this file
+```
+
+```markdown
+![repoglance](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/SRJ-ai/repolens/main/.repolens-badge.json)
+```
+
+### Markdown anywhere
+
+```bash
+repoglance --md   # paste into a PR, wiki, or Slack
+```
+
+## Design goals
+
+- **Fast** — a single `os.walk`, no external services.
+- **Honest** — no network, no telemetry, no surprise writes.
+- **Pretty** — powered by [rich](https://github.com/Textualize/rich).
+- **Scriptable** — everything the report shows is available as `--json`.
+
+## Contributing
+
+Adding a language is a one-line change in `languages.py`. PRs welcome — see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © repoglance contributors