blindspot 0.0.2__tar.gz

blindspot-0.0.2/.blindspot.yaml.example

@@ -0,0 +1,18 @@
+# Example blindspot configuration.
+# Copy to `.blindspot.yaml` (in repo root) or `~/.config/blindspot/config.yaml`
+# and fill in the values you need.
+#
+# Precedence: CLI flags > project (./.blindspot.yaml) > user (~/.config/blindspot/config.yaml).
+# blindspot deliberately does NOT read API keys from environment variables.
+
+narrative:
+  # LLM provider for `--with-narrative`. Currently supported: anthropic.
+  provider: anthropic
+
+  # Override the default model (claude-haiku-4-5-20251001).
+  # Other Claude models: claude-sonnet-4-6, claude-opus-4-7
+  # model: claude-sonnet-4-6
+
+  # API key. Keep this file out of git if you commit your key here —
+  # prefer ~/.config/blindspot/config.yaml or `--api-key` on the command line.
+  api_key: sk-ant-...

blindspot-0.0.2/.gitignore

@@ -0,0 +1,44 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+.venv/
+venv/
+env/
+.env
+
+# Local LLM/API config — may contain api_key.
+.blindspot.yaml
+
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+.idea/
+.vscode/
+.claude/
+*.swp
+.DS_Store
+
+kfactor_report*.html
+demo_report*.html
+# Any report produced from a private/customer repo — keep out of version control.
+report*.html
+report_*.html
+blindspot_report*.html
+blindspot_departure*.html
+departure_*.html
+kfactor.db
+*.sqlite
+*.sqlite3

blindspot-0.0.2/CHANGELOG.md

@@ -0,0 +1,72 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.0.2] — 2026-05-14 (Pre-alpha)
+
+First PyPI release.
+
+### Departure reporting
+- Standalone HTML departure report for the `simulate` command (`--output`)
+- "Departure scenarios" and "Central models" sections in the scan report
+- Named fragility patterns on recommendations: review-without-scrutiny,
+  single-owner-concentration, velocity-without-review
+
+### Dependency graph
+- Auto-detect code root (`src/` / `lib/` / `app/`); test, example, and
+  docs directories are excluded from the structural graph by default
+- AST-based Python extractor: import resolution, class-inheritance edges,
+  and data-model detection (dataclass, pydantic, attrs, msgspec, …)
+- Module aggregation peels the common parent prefix so internal
+  architecture is visible
+
+### Review-data providers
+- Bitbucket Cloud provider (remote detection, REST v2.0 client,
+  app-password auth) — `--with-reviews` now works on Bitbucket repos
+- Shared provider-agnostic pull-request models
+- `--github-token` flag and `github:` config block for private repos
+  without the `gh` CLI
+
+### Documentation
+- New `docs/` folder: overview, quickstart, architecture, algorithms,
+  CLI reference, configuration, outputs, and glossary
+
+## [0.0.1] — 2026-05-13 (Pre-alpha)
+
+Initial public release.
+
+### Knowledge map
+- Ownership engine with recency- and review-weighted contribution scoring
+- Bus factor per file and per service (top-level directory)
+- Review-graph reviewer-coverage analysis
+- File-level dependency graph with PageRank-based structural importance
+- Module-level Mermaid diagram in the HTML report
+
+### AI risk signals
+- "Fake velocity" detector for AI-amplified commits
+- Commit quality heuristics (size, churn, review depth)
+- Per-author AI-usage profile
+
+### Departure simulation
+- Per-person knowledge-loss projection
+- Service-level impact when one or more people leave
+
+### Reporting
+- Single self-contained HTML report (Jinja2 template, embedded styles)
+- Recommender engine: risk → prioritised, deduplicated action list
+- Importance threshold filtering across recommendations and display tables
+- Optional LLM-generated executive summary (Anthropic backend, TR/EN)
+
+### Languages supported by the dependency extractor
+Python · JavaScript / TypeScript (incl. `.mjs`, `.cjs`, JSX, TSX) ·
+C# + F# · Java · Kotlin · Go · Rust · C/C++ · Ruby · PHP · Swift.
+Opt-in `--llm-graph` flag augments the static result with an LLM call.
+
+### Other
+- CODEOWNERS parser with team-only fallback messaging
+- Trend module (time-series view over the configured window)
+- GitHub PR + reviewer + diffstat collector (`--with-reviews`)
+- Configurable via CLI flags, `.blindspot.yaml` (project), or
+  `~/.config/blindspot/config.yaml` (user). API keys are never read from
+  environment variables.

blindspot-0.0.2/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing
+
+Thanks for your interest in blindspot. This project is in pre-alpha — APIs,
+metrics, and CLI surface will change. Small, focused contributions are very
+welcome.
+
+## Dev setup
+
+```bash
+python3.11 -m venv .venv
+.venv/bin/pip install -e ".[dev,ai]"
+```
+
+The `dev` extra pulls in `pytest`, `pytest-cov`, `ruff`, and `mypy`. The
+`ai` extra pulls in `litellm` for the optional LLM features.
+
+## Running the tests
+
+```bash
+.venv/bin/pytest -q
+```
+
+Tests are deterministic and run against synthetic git repositories built
+in-memory (see `tests/conftest.py`). They do not hit the network or any
+real LLM provider.
+
+For type checks and lint:
+
+```bash
+.venv/bin/ruff check .
+.venv/bin/mypy src
+```
+
+## Submitting changes
+
+- Keep PRs focused on a single concern. Mixing a bug fix with a refactor
+  makes review and bisection harder.
+- Add a test for any behaviour change. Reproduce the bug or feature in a
+  failing test first when you can.
+- Update `CHANGELOG.md` if your change is user-visible (new flag, new
+  recommendation rule, breaking output).
+- Update the README only when the change affects documented usage.
+
+## API keys
+
+Blindspot deliberately does **not** read API keys from environment
+variables. Configure providers via:
+
+- `./.blindspot.yaml` (project, in your CWD)
+- `~/.config/blindspot/config.yaml` (user)
+- CLI flags (`--api-key`, `--model`, `--provider`)
+
+Never commit a real key. `.blindspot.yaml` is already in `.gitignore`;
+use `.blindspot.yaml.example` as a template.
+
+## Reporting issues
+
+Use GitHub Issues. Include:
+- The exact command you ran.
+- The repo characteristics that matter (rough size, languages, whether
+  CODEOWNERS or `--with-reviews` was involved).
+- The actual output and what you expected.
+
+If you suspect a privacy issue (e.g. raw author identifiers in a place
+they shouldn't be), please flag it explicitly so it can be triaged ahead
+of other reports.

blindspot-0.0.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aydın Çetin
+
+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.

blindspot-0.0.2/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: blindspot
+Version: 0.0.2
+Summary: The bus factor for the AI era. Map team knowledge blindspots before someone leaves.
+Project-URL: Homepage, https://github.com/aydincn/blindspot
+Project-URL: Repository, https://github.com/aydincn/blindspot
+Project-URL: Documentation, https://github.com/aydincn/blindspot/tree/main/docs
+Project-URL: Changelog, https://github.com/aydincn/blindspot/blob/main/CHANGELOG.md
+Author: Aydın Çetin
+License: MIT
+License-File: LICENSE
+Keywords: bus-factor,code-analysis,engineering-resilience,knowledge-graph,ownership
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: gitpython>=3.1.40
+Requires-Dist: jinja2>=3.1
+Requires-Dist: networkx>=3.2
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: ai
+Requires-Dist: litellm>=1.40; extra == 'ai'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# blindspot
+
+**The bus factor for the AI era.** Map your team's knowledge blindspots before someone leaves.
+
+> 🚧 **Pre-alpha.** Codename: *Blindspot*. APIs and metrics will change.
+
+## Why
+
+AI coding tools made engineering teams faster. But faster does not mean *understood*. Codebases now carry a new kind of risk: services that shipped quickly, owned by one person, reviewed by no one in depth — and that one person can leave tomorrow.
+
+Existing tools measure velocity. **blindspot measures resilience.**
+
+## What it measures
+
+- **Ownership concentration** — who *actually* understands each part of the codebase, weighted by recency and review depth
+- **Bus factor** per service / folder — how many people would need to leave before knowledge is critically lost
+- **Review lineage** — who reviews what, and where reviewer redundancy is dangerously thin
+- **Departure simulation** — *"If two senior devs on Payment leave next month, what coverage do we lose?"*
+- **Knowledge decay** — code volatility and contributor drift, projected 30 / 60 / 90 days forward
+
+## Quick start
+
+```bash
+pip install blindspot
+blindspot scan /path/to/repo --output blindspot_report.html
+blindspot simulate --person alice@example.com /path/to/repo
+```
+
+Output is a single self-contained HTML file. No server, no signup, no telemetry.
+
+## Documentation
+
+Full end-to-end documentation lives in [docs/](docs/README.md) — the
+algorithms (with formulas and parameters), the architecture, the CLI
+reference, configuration, and how to read every section of the report.
+
+## Design principles
+
+- **Service-first, not person-first.** Default views show service-level risk. Individual views require explicit, justified access.
+- **Evidence over inference.** AI-usage signals come from official telemetry (e.g. GitHub Copilot Usage API) when available — not from guessing.
+- **Reports, not surveillance.** blindspot answers *"is this service fragile?"*, not *"is this person slacking?"*.
+
+## Roadmap
+
+| Phase | Surface | Status |
+|---|---|---|
+| 1 | CLI + static HTML report | In progress |
+| 1 | GitHub Action + Checks API output | Planned |
+| 2 | Self-hosted dashboard | Planned |
+| 2 | AI signal layer (Copilot Usage API) | Planned |
+| 3 | Slack / Jira / incident integration | Planned |
+
+## License
+
+MIT. See [LICENSE](LICENSE).

blindspot-0.0.2/README.md

@@ -0,0 +1,55 @@
+# blindspot
+
+**The bus factor for the AI era.** Map your team's knowledge blindspots before someone leaves.
+
+> 🚧 **Pre-alpha.** Codename: *Blindspot*. APIs and metrics will change.
+
+## Why
+
+AI coding tools made engineering teams faster. But faster does not mean *understood*. Codebases now carry a new kind of risk: services that shipped quickly, owned by one person, reviewed by no one in depth — and that one person can leave tomorrow.
+
+Existing tools measure velocity. **blindspot measures resilience.**
+
+## What it measures
+
+- **Ownership concentration** — who *actually* understands each part of the codebase, weighted by recency and review depth
+- **Bus factor** per service / folder — how many people would need to leave before knowledge is critically lost
+- **Review lineage** — who reviews what, and where reviewer redundancy is dangerously thin
+- **Departure simulation** — *"If two senior devs on Payment leave next month, what coverage do we lose?"*
+- **Knowledge decay** — code volatility and contributor drift, projected 30 / 60 / 90 days forward
+
+## Quick start
+
+```bash
+pip install blindspot
+blindspot scan /path/to/repo --output blindspot_report.html
+blindspot simulate --person alice@example.com /path/to/repo
+```
+
+Output is a single self-contained HTML file. No server, no signup, no telemetry.
+
+## Documentation
+
+Full end-to-end documentation lives in [docs/](docs/README.md) — the
+algorithms (with formulas and parameters), the architecture, the CLI
+reference, configuration, and how to read every section of the report.
+
+## Design principles
+
+- **Service-first, not person-first.** Default views show service-level risk. Individual views require explicit, justified access.
+- **Evidence over inference.** AI-usage signals come from official telemetry (e.g. GitHub Copilot Usage API) when available — not from guessing.
+- **Reports, not surveillance.** blindspot answers *"is this service fragile?"*, not *"is this person slacking?"*.
+
+## Roadmap
+
+| Phase | Surface | Status |
+|---|---|---|
+| 1 | CLI + static HTML report | In progress |
+| 1 | GitHub Action + Checks API output | Planned |
+| 2 | Self-hosted dashboard | Planned |
+| 2 | AI signal layer (Copilot Usage API) | Planned |
+| 3 | Slack / Jira / incident integration | Planned |
+
+## License
+
+MIT. See [LICENSE](LICENSE).

blindspot-0.0.2/docs/README.md

@@ -0,0 +1,65 @@
+# Blindspot Documentation
+
+**Blindspot** is the bus factor for the AI era — a static analysis tool
+that maps where a team's engineering knowledge is thin, concentrated, or
+decaying, and produces a single self-contained HTML report. No server,
+no database, no telemetry.
+
+This folder is the complete reference. The goal: after reading it, no
+question marks remain about what Blindspot does, how it computes any
+number, or how to read its output.
+
+---
+
+## Contents
+
+| Document | What's in it |
+|---|---|
+| [overview.md](overview.md) | The problem Blindspot solves, the design principles, the full capability matrix, and the honest limitations. |
+| [quickstart.md](quickstart.md) | Install and get your first report out in five minutes. |
+| [architecture.md](architecture.md) | The 13 modules, how data flows between them, and the exact step order of the `scan` and `simulate` pipelines. |
+| [algorithms.md](algorithms.md) | The core reference — every one of the ~17 algorithms with its exact formula, every parameter and threshold, and the output type. |
+| [cli-reference.md](cli-reference.md) | Every command and every flag, with defaults and meanings. |
+| [configuration.md](configuration.md) | The `.blindspot.yaml` file, credential precedence, and GitHub / Bitbucket integration setup. |
+| [outputs.md](outputs.md) | Every section of the HTML report explained — what it shows, how to read it, which algorithm feeds it. |
+| [glossary.md](glossary.md) | One-line definitions of every term. |
+
+---
+
+## Read in this order
+
+**If you're new to Blindspot:**
+1. [overview.md](overview.md) — understand what it is and why.
+2. [quickstart.md](quickstart.md) — run it once.
+3. [outputs.md](outputs.md) — read the report you just generated.
+
+**If you want to understand a specific number:**
+- [algorithms.md](algorithms.md) — find the metric, read its formula
+  and parameters.
+- [glossary.md](glossary.md) — if a term is unfamiliar.
+
+**If you're setting up review data or the LLM features:**
+- [configuration.md](configuration.md) — config file + auth.
+- [cli-reference.md](cli-reference.md) — the relevant flags.
+
+**If you're working on the code:**
+- [architecture.md](architecture.md) — module map and pipelines.
+- [algorithms.md](algorithms.md) — every formula traced to its source
+  file and line.
+
+---
+
+## Conventions
+
+- Every formula in [algorithms.md](algorithms.md) is traced to a source
+  file (and often a line number) so it can be re-verified against the
+  code if it ever drifts.
+- "Parameters" tables list the dataclass default — the value you get
+  unless you override it.
+- Sections marked *(only with `--flag`)* in [outputs.md](outputs.md) are
+  conditional on a CLI flag.
+
+---
+
+*Documentation for Blindspot 0.0.1 (pre-alpha). The CLI surface and
+metrics will change; this folder is kept in sync with the code.*