Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat: add overview dashboard, background pipeline execution, and shared (#38)

Swati Ahujae26944efe9d4
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 0dedb77cc..c93f73796 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -132,6 +132,10 @@ repowise/
│ │ │ │ ├── fetcher.py # EditorFileDataFetcher (DB → EditorFileData)
│ │ │ │ ├── tech_stack.py # filesystem tech stack + build command detection
│ │ │ │ └── claude_md.py # ClaudeMdGenerator subclass
+│ │ │ ├── pipeline/
+│ │ │ │ ├── orchestrator.py # run_pipeline(), PipelineResult
+│ │ │ │ ├── persist.py # persist_pipeline_result() — shared by CLI + server
+│ │ │ │ └── progress.py # ProgressCallback protocol + LoggingProgressCallback
│ │ │ ├── persistence/
│ │ │ │ ├── models.py # SQLAlchemy ORM models
│ │ │ │ ├── crud.py # async CRUD layer
@@ -165,6 +169,7 @@ repowise/
│ │ ├── routers/ # FastAPI routers (repos, pages, jobs, symbols, graph, git, dead-code, decisions, search, claude-md)
│ │ ├── mcp_server/ # MCP server package (8 tools, split into focused modules)
│ │ ├── webhooks/ # GitHub + GitLab handlers
+│ │ ├── job_executor.py # Background pipeline executor — bridges REST endpoints to core pipeline
│ │ └── scheduler.py # APScheduler background jobs
│ │
│ ├── cli/ # Python: repowise CLI (click + rich)
@@ -172,9 +177,9 @@ repowise/
│ │ └── commands/ # init, update, watch, serve, search, export, status, doctor, dead-code, decision, mcp, reindex, generate-claude-md
│ │
│ └── web/ # Next.js 15 frontend
-│ ├── src/app/ # App Router pages (dashboard, wiki, search, graph, symbols, …)
-│ ├── src/components/ # UI primitives, layout, wiki, repos, jobs, settings
-│ └── src/lib/ # API client, SWR hooks, utilities, design tokens
+│ ├── src/app/ # App Router pages (dashboard, wiki, search, graph, symbols, overview, …)
+│ ├── src/components/ # UI primitives, layout, wiki, repos, jobs, settings, dashboard
+│ └── src/lib/ # API client, SWR hooks, utilities (health-score, format), design tokens
│
├── integrations/
│ ├── github-action/ # action.yml + Dockerfile entrypoint
@@ -613,6 +618,46 @@ are skipped, and generation continues from the last checkpoint.
`repowise init` is fully idempotent. Running it twice produces the same result.
Running it after a partial previous run completes only the remaining pages.
+### 5.7 Shared Persistence (`pipeline/persist.py`)
+
+The persistence logic for storing a `PipelineResult` into the database (graph nodes,
+edges, symbols, pages, git metadata, dead code findings, decision records) was
+extracted from the CLI's `init_cmd.py` into `core/pipeline/persist.py`. Both the
+CLI and the server's background job executor call `persist_pipeline_result()` — zero
+duplication.
+
+FTS indexing is intentionally excluded from this function. Callers must run it
+separately after the session closes to avoid SQLite write-lock conflicts.
+
+### 5.8 Background Job Executor (`server/job_executor.py`)
+
+The server can now run full pipeline jobs in the background, triggered by the
+`POST /api/repos/{id}/sync` and `POST /api/repos/{id}/full-resync` endpoints.
+
+`execute_job()` is the single entry point, launched via `asyncio.create_task()`:
+
+1. Marks the job as `running`
+2. Resolves the LLM provider from server config
+3. Runs `run_pipeline()` with a `JobProgressCallback` that writes progress to the
+ `GenerationJob` table (the SSE stream endpoint polls this table)
+4. Persists results via `persist_pipeline_result()`
+5. Marks the job as `completed` (or `failed` on error)
+
+Progress updates are batched (every 5 items) to avoid per-item DB overhead. Before
+writing the final job status, all in-flight progress tasks are drained to prevent a
+late `running` update from overwriting `completed`.
+
+Concurrent pipeline runs on the same repository are prevented at the endpoint level
+(returns HTTP 409 if a pending/running job already exists).
+
+### 5.9 Async Pipeline Improvements
+
+The pipeline orchestrator now keeps the event loop responsive during CPU-bound work:
+- File I/O uses `asyncio.wrap_future()` instead of blocking `as_completed()`
+- Graph building runs in a thread via `asyncio.to_thread()`
+- The parse loop yields control every 50 files with `asyncio.sleep(0)`
+- Thread pool shutdown is non-blocking via `asyncio.to_thread()`
+
---
## 6. Maintenance Path — Keeping Docs in Sync
@@ -983,7 +1028,7 @@ and Cline. This config is printed at the end of `repowise init`.
Served on port `7337` alongside the web UI. All endpoints are prefixed with `/api/`.
Key routers:
-- `/api/repos` — register repos, trigger sync, full-resync
+- `/api/repos` — register repos, trigger sync, full-resync (now launches background pipeline jobs with concurrent-run prevention)
- `/api/pages` — read pages, version history, force-regenerate single page
- `/api/search` — semantic (LanceDB or pgvector) and full-text (SQLite FTS5 / PostgreSQL tsvector) search
- `/api/jobs` — job status, SSE stream for live progress updates
@@ -1004,6 +1049,12 @@ Key routers:
- `/health` — liveness + readiness (checks DB + provider)
- `/metrics` — Prometheus-compatible metrics (job counts, token totals, stale count)
+**Server lifecycle:**
+- On startup, any jobs left in `running` state from a previous server instance are
+ automatically reset to `failed` (crash recovery).
+- Background pipeline tasks are tracked in `app.state.background_tasks` to prevent
+ garbage collection of `asyncio.Task` references.
+
Authentication is optional. Set `REPOWISE_API_KEY` to require bearer token auth on
all non-`/health` endpoints. Default (no key set): fully open, suitable for local use.
@@ -1014,7 +1065,8 @@ Served from the same port as the API. All routes under `/`:
| Route | Content |
|-------|---------|
| `/` | Dashboard: all repos, recent jobs, stale page counts, token usage |
-| `/repos/[id]` | Repo overview wiki page + file tree sidebar |
+| `/repos/[id]` | Repo layout with file tree sidebar |
+| `/repos/[id]/overview` | **Overview dashboard** — health score ring, attention panel, language donut, ownership treemap, hotspots mini, decisions timeline, module minimap, quick actions, active job banner |
| `/repos/[id]/wiki/[...slug]` | Individual wiki page with MDX rendering |
| `/repos/[id]/search` | Semantic search results |
| `/repos/[id]/graph` | D3 force-directed dependency graph |
@@ -1023,6 +1075,8 @@ Served from the same port as the API. All routes under `/`:
| `/repos/[id]/ownership` | Ownership treemap — files colored by primary owner, sized by LOC |
| `/repos/[id]/hotspots` | Hotspot list — top 20 files with churn + complexity bars |
| `/repos/[id]/dead-code` | Dead code report — three tabs: Files, Exports, Internals |
+| `/repos/[id]/decisions` | Architectural decision records |
+| `/repos/[id]/chat` | Codebase chat with streaming LLM responses |
| `/settings` | Provider config, polling interval, cascade budget |
**Key rendering behavior:**
@@ -1201,6 +1255,33 @@ repos.last_sync_commit = HEAD
state.json updated
```
+### Server-triggered pipeline flow
+
+```
+Web UI "Sync" / "Full Re-index" button
+ │
+ ▼
+POST /api/repos/{id}/sync (or /full-resync)
+ │
+ ├── Check: no pending/running job for this repo (else → 409)
+ ▼
+Create GenerationJob (status=pending, commit)
+ │
+ ▼
+asyncio.create_task(execute_job(job_id, app_state))
+ │ (strong ref in app.state.background_tasks)
+ ▼
+execute_job():
+ ├── Mark job "running"
+ ├── Resolve LLM provider from server config
+ ├── run_pipeline() with JobProgressCallback
+ │ └── writes progress to GenerationJob table every 5 items
+ ├── persist_pipeline_result() (shared with CLI)
+ ├── FTS index new pages
+ ├── drain_and_stop() progress tasks
+ └── Mark job "completed" (or "failed" on error)
+```
+
### MCP query flow
```
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index e59274687..4614ab62c 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -12,6 +12,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
### Added
+- **Overview dashboard** (`/repos/[id]/overview`) — new landing page for each repository with:
+ - Health score ring (composite of doc coverage, freshness, dead code, hotspot density, silo risk)
+ - Attention panel highlighting items needing action (stale docs, high-risk hotspots, dead code)
+ - Language donut chart, ownership treemap, hotspots mini-list
+ - Decisions timeline, module minimap (interactive graph summary)
+ - Quick actions panel (sync, full re-index, generate CLAUDE.md, export)
+ - Active job banner with live progress polling
+- **Background pipeline execution** — `POST /api/repos/{id}/sync` and `POST /api/repos/{id}/full-resync` now launch the full pipeline in the background instead of only creating a pending job. Concurrent runs on the same repo return HTTP 409.
+- **Shared persistence layer** (`core/pipeline/persist.py`) — `persist_pipeline_result()` extracted from CLI, reused by both CLI and server job executor
+- **Job executor** (`server/job_executor.py`) — background task that runs `run_pipeline()`, writes progress to the `GenerationJob` table, and persists all results
+- **Server crash recovery** — stale `running` jobs are reset to `failed` on server startup
+- **Async pipeline improvements** — `asyncio.wrap_future` for file I/O, `asyncio.to_thread` for graph building and thread pool shutdown, periodic `asyncio.sleep(0)` yields during parsing
+- **Health score utility** (`web/src/lib/utils/health-score.ts`) — composite health score computation, attention item builder, and language aggregation for the overview dashboard
+
+### Changed
+- `init_cmd.py` refactored to use shared `persist_pipeline_result()` instead of inline persistence logic
+- Pipeline orchestrator uses async-friendly patterns to keep the event loop responsive during ingestion
+- Sidebar and mobile nav updated to include "Overview" link
+
- Monorepo scaffold: uv workspace with `packages/core`, `packages/cli`, `packages/server`, `packages/web`
- Provider abstraction layer: `BaseProvider`, `GeneratedResponse`, `ProviderError`, `RateLimitError`
- `AnthropicProvider` with prompt caching support
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 8d0d92b48..f022aae53 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -91,7 +91,7 @@ repowise watch
## Web UI
-Repowise includes a full web dashboard with a wiki browser, interactive dependency graph, codebase chat, search, code ownership, hotspots, and dead code detection.
+Repowise includes a full web dashboard with a repository overview, wiki browser, interactive dependency graph, codebase chat, search, code ownership, hotspots, and dead code detection. The overview page shows a health score, attention items, language breakdown, ownership treemap, and quick actions.
### With Node.js installed
diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md
index eb5cc24f1..af147df8c 100644
--- a/docs/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@@ -616,6 +616,20 @@ Open **http://localhost:3000** in your browser.
**Dashboard** (`/`)
Home page with aggregate stats (total pages, fresh/stale counts, dead code findings), a list of indexed repositories, and recent job status.
+**Repository Overview** (`/repos/[id]/overview`)
+A single-page dashboard for each repository that aggregates key health signals. Includes:
+- **Health score ring** — composite score (0–100) computed from documentation coverage, freshness, dead code ratio, hotspot density, and ownership silo risk
+- **Attention panel** — prioritized list of items needing action (stale docs, high-churn hotspots, dead code findings)
+- **Language donut** — breakdown of codebase by programming language
+- **Ownership treemap** — visualizes code ownership distribution across modules
+- **Hotspots mini** — top high-churn files at a glance
+- **Decisions timeline** — recent architectural decisions
+- **Module minimap** — compact interactive graph of module relationships
+- **Quick actions** — one-click buttons for sync, full re-index, CLAUDE.md generation, and export
+- **Active job banner** — shows progress of running pipeline jobs with live polling
+
+The overview page degrades gracefully — each data section loads independently, so partial data (e.g., missing git metadata) still renders a useful dashboard.
+
**Wiki Browser** (`/repos/[id]/wiki/...`)
The heart of repowise. Browse AI-generated documentation for every file and module. Each page includes:
- Rendered markdown with syntax-highlighted code blocks and Mermaid diagrams
diff --git a/packages/cli/src/repowise/cli/commands/init_cmd.py b/packages/cli/src/repowise/cli/commands/init_cmd.py
index 96efa6cb8..10312ea9c 100644
--- a/packages/cli/src/repowise/cli/commands/init_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/init_cmd.py
@@ -134,113 +134,35 @@ async def _persist_result(
"""
from repowise.cli.helpers import get_db_url_for_repo
from repowise.core.persistence import (
- batch_upsert_graph_edges,
- batch_upsert_graph_nodes,
- batch_upsert_symbols,
+ FullTextSearch,
create_engine,
create_session_factory,
get_session,
init_db,
upsert_repository,
)
- from repowise.core.persistence.crud import (
- save_dead_code_findings,
- upsert_git_metadata_bulk,
- )
+ from repowise.core.pipeline import persist_pipeline_result
url = get_db_url_for_repo(repo_path)
engine = create_engine(url)
await init_db(engine)
sf = create_session_factory(engine)
+ fts = None
+ if result.generated_pages:
+ fts = FullTextSearch(engine)
+ await fts.ensure_index()
+
async with get_session(sf) as session:
repo = await upsert_repository(
session,
name=result.repo_name,
local_path=str(repo_path),
)
- repo_id = repo.id
-
- # Pages (if generated)
- if result.generated_pages:
- from repowise.core.persistence import upsert_page_from_generated
-
- for page in result.generated_pages:
- await upsert_page_from_generated(session, page, repo_id)
-
- # Graph nodes
- graph = result.graph_builder.graph()
- pr = result.graph_builder.pagerank()
- bc = result.graph_builder.betweenness_centrality()
- cd = result.graph_builder.community_detection()
- nodes = []
- for node_path in graph.nodes:
- data = graph.nodes[node_path]
- nodes.append(
- {
- "node_id": node_path,
- "symbol_count": data.get("symbol_count", 0),
- "has_error": data.get("has_error", False),
- "is_test": data.get("is_test", False),
- "is_entry_point": data.get("is_entry_point", False),
- "language": data.get("language", "unknown"),
- "pagerank": pr.get(node_path, 0.0),
- "betweenness": bc.get(node_path, 0.0),
- "community_id": cd.get(node_path, 0),
- }
- )
- if nodes:
- await batch_upsert_graph_nodes(session, repo_id, nodes)
-
- # Graph edges
- edges = []
- for u, v, data in graph.edges(data=True):
- edges.append(
- {
- "source_node_id": u,
- "target_node_id": v,
- "imported_names_json": json.dumps(data.get("imported_names", [])),
- "edge_type": data.get("edge_type", "imports"),
- }
- )
- if edges:
- await batch_upsert_graph_edges(session, repo_id, edges)
-
- # Symbols
- all_symbols = []
- for pf in result.parsed_files:
- for sym in pf.symbols:
- sym.file_path = pf.file_info.path
- all_symbols.append(sym)
- if all_symbols:
- await batch_upsert_symbols(session, repo_id, all_symbols)
-
- # Git metadata
- if result.git_metadata_list:
- await upsert_git_metadata_bulk(session, repo_id, result.git_metadata_list)
-
- # Dead code findings
- if result.dead_code_report and result.dead_code_report.findings:
- await save_dead_code_findings(session, repo_id, result.dead_code_report.findings)
-
- # Decision records
- if result.decision_report and result.decision_report.decisions:
- import dataclasses as _dc
-
- from repowise.core.persistence.crud import bulk_upsert_decisions
-
- await bulk_upsert_decisions(
- session,
- repo_id,
- [_dc.asdict(d) for d in result.decision_report.decisions],
- )
-
- # FTS indexing (only when pages were generated)
- if result.generated_pages:
- from repowise.core.persistence import FullTextSearch
+ await persist_pipeline_result(result, session, repo.id)
- fts = FullTextSearch(engine)
- await fts.ensure_index()
+ # FTS indexing is done outside the session to avoid SQLite write conflicts
+ if fts is not None and result.generated_pages:
for page in result.generated_pages:
await fts.index(page.page_id, page.title, page.content)
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer.py b/packages/core/src/repowise/core/ingestion/git_indexer.py
index aa8e07acb..db4a643d0 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer.py
+++ b/packages/core/src/repowise/core/ingestion/git_indexer.py
@@ -200,6 +200,47 @@ _MAX_BLAME_SIZE_BYTES: int = 100 * 1024 # 100 KB
_FILE_INDEX_TIMEOUT_SECS: float = 45.0
+@dataclass
+class _CommitRec:
+ """Lightweight commit record parsed from ``git log --numstat``."""
+
+ sha: str
+ author_name: str
+ author_email: str
+ ts: int # unix epoch
+ is_merge: bool
+ subject: str
+ added: int = 0
+ deleted: int = 0
+
+
+_RENAME_RE = re.compile(r"\{(.+?) => (.+?)\}")
+
+
+def _extract_rename_paths(stat_path: str, known_paths: set[str]) -> tuple[str | None, str | None]:
+ """Extract old/new paths from a git numstat rename line and add to *known_paths*.
+
+ Git ``--numstat`` with ``--follow`` emits rename lines like::
+
+ 10\t5\t{old => new}/shared_suffix
+ 10\t5\told_dir/{old_name => new_name}.py
+
+ This helper parses both forms, adds both expanded paths to *known_paths*,
+ and returns ``(old_path, new_path)`` so the caller can attribute churn to
+ the correct file. Returns ``(None, None)`` if the pattern is not found.
+ """
+ m = _RENAME_RE.search(stat_path)
+ if m:
+ prefix = stat_path[: m.start()]
+ suffix = stat_path[m.end() :]
+ old_path = prefix + m.group(1) + suffix
+ new_path = prefix + m.group(2) + suffix
+ known_paths.add(old_path)
+ known_paths.add(new_path)
+ return old_path, new_path
+ return None, None
+
+
def _should_skip_index(file_path: str) -> bool:
"""Return True for files where per-file git indexing should be skipped.
@@ -471,10 +512,18 @@ class GitIndexer:
return []
def _index_file(self, file_path: str, repo: Any) -> dict:
- """Index a single file's git history. Runs in executor."""
+ """Index a single file's git history. Runs in executor.
+
+ Uses a single ``git log --numstat`` call to collect commit metadata,
+ line-churn stats, and merge-commit flag in one subprocess instead of
+ the previous three separate calls (_get_commits, _get_line_stats,
+ _get_merge_commit_count).
+ """
now = datetime.now(UTC)
ninety_days_ago = now - timedelta(days=90)
thirty_days_ago = now - timedelta(days=30)
+ ninety_days_ago_ts = ninety_days_ago.timestamp()
+ thirty_days_ago_ts = thirty_days_ago.timestamp()
meta: dict[str, Any] = {
"file_path": file_path,
@@ -509,10 +558,81 @@ class GitIndexer:
}
try:
- commits = self._get_commits(file_path, repo)
+ # Single git log call: header line + optional numstat lines per commit.
+ # Format: NUL-delimited record per commit so we can split reliably.
+ # Fields: sha, author name, author email, unix timestamp, parent SHAs, subject
+ log_args: list[str] = []
+ if self.follow_renames:
+ log_args.append("--follow")
+ log_args += [
+ f"-{self.commit_limit}",
+ "--numstat",
+ "--format=%x00%H%x1f%an%x1f%ae%x1f%ct%x1f%P%x1f%s",
+ "--",
+ file_path,
+ ]
+ raw = repo.git.log(*log_args)
except Exception:
return meta
+ if not raw.strip():
+ return meta
+
+ # Parse records — each starts with a \x00 marker line followed by
+ # zero-or-more numstat lines (added\tdeleted\tpath).
+ # When --follow is active, older commits may reference previous file
+ # names so we track all names seen via rename markers ("{old => new}").
+ known_paths: set[str] = {file_path}
+ # When --follow is active, seed known_paths with the original path
+ # so that numstat lines referencing the old name (without a rename
+ # marker in the log window) are still counted.
+ orig_path: str | None = None
+ if self.follow_renames:
+ orig_path = self._detect_original_path(file_path, repo)
+ if orig_path:
+ known_paths.add(orig_path)
+ commits: list[_CommitRec] = []
+ current: _CommitRec | None = None
+
+ for line in raw.splitlines():
+ if line.startswith("\x00"):
+ parts = line.lstrip("\x00").split("\x1f")
+ if len(parts) >= 6:
+ sha, an, ae, ct, parents, subj = parts[0], parts[1], parts[2], parts[3], parts[4], parts[5]
+ try:
+ ts = int(ct)
+ except ValueError:
+ ts = 0
+ current = _CommitRec(
+ sha=sha,
+ author_name=an or "unknown",
+ author_email=ae,
+ ts=ts,
+ is_merge=len(parents.split()) > 1,
+ subject=subj,
+ )
+ commits.append(current)
+ elif current is not None and line.strip():
+ # numstat line: added\tdeleted\tpath — only count the target file.
+ # With --follow, git may emit rename lines like
+ # "10\t5\t{old_dir => new_dir}/file.py" or just the old path.
+ numstat_parts = line.split("\t")
+ if len(numstat_parts) >= 3:
+ stat_path = numstat_parts[2]
+ # Track renamed paths so we can match them in older commits.
+ # For rename lines the raw stat_path (with {old => new}) won't
+ # match known_paths directly — check the expanded new path instead.
+ match_path = stat_path
+ if "=>" in stat_path:
+ _old, _new = _extract_rename_paths(stat_path, known_paths)
+ match_path = _new or stat_path
+ if match_path in known_paths or match_path == file_path:
+ try:
+ current.added += int(numstat_parts[0]) if numstat_parts[0] != "-" else 0
+ current.deleted += int(numstat_parts[1]) if numstat_parts[1] != "-" else 0
+ except ValueError:
+ pass
+
if not commits:
return meta
@@ -520,30 +640,37 @@ class GitIndexer:
meta["commit_count_capped"] = len(commits) >= self.commit_limit
try:
- # Timeline
- dates = [c.committed_datetime for c in commits]
- meta["first_commit_at"] = min(dates)
- meta["last_commit_at"] = max(dates)
- meta["age_days"] = (now - min(dates)).days
+ timestamps = [c.ts for c in commits if c.ts > 0]
+ if timestamps:
+ first_ts = min(timestamps)
+ last_ts = max(timestamps)
+ meta["first_commit_at"] = datetime.fromtimestamp(first_ts, tz=UTC)
+ meta["last_commit_at"] = datetime.fromtimestamp(last_ts, tz=UTC)
+ meta["age_days"] = (now - datetime.fromtimestamp(first_ts, tz=UTC)).days
- # Commit counts by time window + recent author tracking
author_counts: Counter[str] = Counter()
author_emails: dict[str, str] = {}
recent_author_counts: Counter[str] = Counter()
for c in commits:
- cd = c.committed_datetime
- if cd.tzinfo is None:
- cd = cd.replace(tzinfo=UTC)
- if cd >= ninety_days_ago:
+ is_recent_90 = c.ts >= ninety_days_ago_ts
+ is_recent_30 = c.ts >= thirty_days_ago_ts
+ if is_recent_90:
meta["commit_count_90d"] += 1
- recent_author_counts[c.author.name or "unknown"] += 1
- if cd >= thirty_days_ago:
+ recent_author_counts[c.author_name] += 1
+ meta["lines_added_90d"] += c.added
+ meta["lines_deleted_90d"] += c.deleted
+ if c.is_merge:
+ meta["merge_commit_count_90d"] += 1
+ if is_recent_30:
meta["commit_count_30d"] += 1
- name = c.author.name or "unknown"
- author_counts[name] += 1
- if name not in author_emails and c.author.email:
- author_emails[name] = c.author.email
+ author_counts[c.author_name] += 1
+ if c.author_name not in author_emails and c.author_email:
+ author_emails[c.author_name] = c.author_email
+
+ c90 = meta["commit_count_90d"]
+ total_churn = meta["lines_added_90d"] + meta["lines_deleted_90d"]
+ meta["avg_commit_size"] = total_churn / c90 if c90 > 0 else 0.0
# Contributor count & bus factor
meta["contributor_count"] = len(author_counts)
@@ -590,8 +717,7 @@ class GitIndexer:
# Blame ownership (overrides author-based if available).
# Skipped for large files — git blame is O(lines) and can block the
- # executor thread for many seconds on files > 100 KB. The commit-based
- # ownership computed above is used as a fallback.
+ # executor thread for many seconds on files > 100 KB.
try:
file_size = (self.repo_path / file_path).stat().st_size
if file_size <= _MAX_BLAME_SIZE_BYTES:
@@ -604,91 +730,48 @@ class GitIndexer:
pass # blame is best-effort
# Significant commits + classification + PR extraction
- sig_commits = []
+ sig_commits: list[dict[str, Any]] = []
+ sig_full = False
category_counts: Counter[str] = Counter()
for c in commits:
- msg = c.message.strip().split("\n")[0][:200]
- if self._is_significant_commit(c.message, c.author.name or ""):
+ msg = c.subject[:200]
+ if not sig_full and self._is_significant_commit(msg, c.author_name):
entry: dict[str, Any] = {
- "sha": c.hexsha[:8],
- "date": c.committed_datetime.isoformat(),
+ "sha": c.sha[:8],
+ "date": datetime.fromtimestamp(c.ts, tz=UTC).isoformat() if c.ts else "",
"message": msg,
- "author": c.author.name or "unknown",
+ "author": c.author_name,
}
- # Extract PR/MR number from commit message
- pr_match = _PR_NUMBER_RE.search(c.message)
+ pr_match = _PR_NUMBER_RE.search(msg)
if pr_match:
pr_num = pr_match.group(1) or pr_match.group(2) or pr_match.group(3)
entry["pr_number"] = int(pr_num)
sig_commits.append(entry)
if len(sig_commits) >= 10:
- break
- # Classify ALL commits (not just significant) for accurate ratios
+ sig_full = True
+ # Classify ALL commits for accurate category ratios
for cat, pattern in _COMMIT_CATEGORIES.items():
if pattern.search(msg):
category_counts[cat] += 1
- break # first match wins
+ break
meta["significant_commits_json"] = json.dumps(sig_commits)
meta["commit_categories_json"] = json.dumps(dict(category_counts))
- # Diff stats (lines added/deleted in last 90 days)
- added, deleted = self._get_line_stats(file_path, repo, ninety_days_ago)
- meta["lines_added_90d"] = added
- meta["lines_deleted_90d"] = deleted
- c90 = meta["commit_count_90d"]
- meta["avg_commit_size"] = (added + deleted) / c90 if c90 > 0 else 0.0
-
- # Original path detection (rename tracking)
- if self.follow_renames:
- orig = self._detect_original_path(file_path, repo)
- if orig:
- meta["original_path"] = orig
-
- # Merge commit count (coordination bottleneck signal)
- meta["merge_commit_count_90d"] = self._get_merge_commit_count(
- file_path,
- repo,
- ninety_days_ago,
- )
+ # Original path detection (rename tracking) — reuse the result
+ # from the known_paths seeding above to avoid a duplicate subprocess.
+ if self.follow_renames and orig_path:
+ meta["original_path"] = orig_path
# Stable classification
if meta["commit_count_total"] > 10 and meta["commit_count_90d"] == 0:
meta["is_stable"] = True
except Exception:
- pass # return whatever partial data we have
+ logger.debug("git_indexer_partial_failure", file_path=file_path, exc_info=True)
return meta
- def _get_commits(self, file_path: str, repo: Any) -> list[Any]:
- """Get commits for a file, optionally following renames via --follow."""
- if not self.follow_renames:
- return list(repo.iter_commits(paths=file_path, max_count=self.commit_limit))
-
- # --follow tracks the file across renames; iter_commits doesn't support it.
- # Get SHAs via git log --follow, then resolve to commit objects.
- try:
- raw = repo.git.log(
- "--follow",
- f"-{self.commit_limit}",
- "--format=%H",
- "--",
- file_path,
- )
- except Exception:
- return []
-
- commits = []
- for line in raw.splitlines():
- sha = line.strip()
- if sha:
- try:
- commits.append(repo.commit(sha))
- except Exception:
- continue
- return commits
-
def _detect_original_path(self, file_path: str, repo: Any) -> str | None:
"""If --follow reveals the file was renamed, return its earliest prior path."""
try:
@@ -711,25 +794,6 @@ class GitIndexer:
prev_path = p # keep overwriting — last one is oldest
return prev_path
- def _get_merge_commit_count(
- self,
- file_path: str,
- repo: Any,
- since: datetime,
- ) -> int:
- """Count how many merge commits touched this file since a given date."""
- try:
- raw = repo.git.log(
- "--merges",
- f"--since={since.strftime('%Y-%m-%d')}",
- "--format=%H",
- "--",
- file_path,
- )
- except Exception:
- return 0
- return sum(1 for line in raw.splitlines() if line.strip())
-
def _get_blame_ownership(
self, file_path: str, repo: Any
) -> tuple[str | None, str | None, float | None]:
@@ -758,41 +822,6 @@ class GitIndexer:
pct = line_counts[top_name] / total_lines
return top_name, emails.get(top_name), pct
- def _get_line_stats(
- self,
- file_path: str,
- repo: Any,
- since: datetime,
- ) -> tuple[int, int]:
- """Get total lines added and deleted for a file since a given date.
-
- Uses a single ``git log --numstat`` call — one subprocess per file.
- """
- try:
- output = repo.git.log(
- f"--since={since.strftime('%Y-%m-%d')}",
- "--numstat",
- "--format=",
- "--",
- file_path,
- )
- except Exception:
- return 0, 0
-
- added = 0
- deleted = 0
- for line in output.splitlines():
- parts = line.split("\t")
- if len(parts) >= 2:
- try:
- a = int(parts[0]) if parts[0] != "-" else 0
- d = int(parts[1]) if parts[1] != "-" else 0
- added += a
- deleted += d
- except ValueError:
- continue
- return added, deleted
-
def _is_significant_commit(self, message: str, author: str) -> bool:
"""Return True if the commit is considered significant.
diff --git a/packages/core/src/repowise/core/pipeline/__init__.py b/packages/core/src/repowise/core/pipeline/__init__.py
index d4fa9eb29..77258a054 100644
--- a/packages/core/src/repowise/core/pipeline/__init__.py
+++ b/packages/core/src/repowise/core/pipeline/__init__.py
@@ -11,12 +11,14 @@ Usage::
"""
from .orchestrator import PipelineResult, run_generation, run_pipeline
+from .persist import persist_pipeline_result
from .progress import LoggingProgressCallback, ProgressCallback
__all__ = [
"LoggingProgressCallback",
"PipelineResult",
"ProgressCallback",
+ "persist_pipeline_result",
"run_generation",
"run_pipeline",
]
diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.py
index 420599a56..472582bee 100644
--- a/packages/core/src/repowise/core/pipeline/orchestrator.py
+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py
@@ -14,8 +14,9 @@ Callers:
from __future__ import annotations
+import asyncio
import time
-from concurrent.futures import ThreadPoolExecutor, as_completed
+from concurrent.futures import ThreadPoolExecutor
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
@@ -292,19 +293,29 @@ async def _run_ingestion(
if progress:
progress.on_phase_start("traverse", len(all_paths))
- # Parallel stat + header reads (I/O bound)
+ # Parallel stat + header reads (I/O bound).
+ # Use asyncio.wrap_future so the event loop stays responsive while waiting.
file_infos: list[Any] = []
- with ThreadPoolExecutor(max_workers=8) as io_pool:
- futures = [io_pool.submit(traverser._build_file_info, p) for p in all_paths]
- for future in as_completed(futures):
+ io_pool = ThreadPoolExecutor(max_workers=8)
+ try:
+ aws = [
+ asyncio.wrap_future(io_pool.submit(traverser._build_file_info, p))
+ for p in all_paths
+ ]
+ for coro in asyncio.as_completed(aws):
try:
- result = future.result()
+ result = await coro
except Exception:
result = None
if result is not None:
file_infos.append(result)
if progress:
progress.on_item_done("traverse")
+ finally:
+ # shutdown(wait=True) is blocking — run in a thread to keep the
+ # event loop responsive. All submitted futures have already
+ # completed by the time we reach here (the for-loop awaited them).
+ await asyncio.to_thread(io_pool.shutdown, wait=True)
repo_structure = traverser.get_repo_structure(file_infos)
@@ -327,7 +338,7 @@ async def _run_ingestion(
source_map: dict[str, bytes] = {}
graph_builder = GraphBuilder()
- for fi in file_infos:
+ for i, fi in enumerate(file_infos):
try:
source = Path(fi.abs_path).read_bytes()
parsed = parser.parse_file(fi, source)
@@ -338,11 +349,14 @@ async def _run_ingestion(
pass # skip unparseable files
if progress:
progress.on_item_done("parse")
+ # Yield control every 50 files so the event loop stays responsive
+ if i % 50 == 49:
+ await asyncio.sleep(0)
- # Build graph
+ # Build graph (CPU-bound — run in thread to keep event loop free)
if progress:
progress.on_phase_start("graph", 1)
- graph_builder.build()
+ await asyncio.to_thread(graph_builder.build)
# Add framework-aware synthetic edges (conftest, Django, FastAPI, Flask)
try:
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
new file mode 100644
index 000000000..78af26503
--- /dev/null
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -0,0 +1,134 @@
+"""Shared persistence logic for pipeline results.
+
+Extracted from ``cli/commands/init_cmd.py`` so both the CLI and the server
+can persist a ``PipelineResult`` without duplicating the upsert recipe.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+async def persist_pipeline_result(
+ result: Any,
+ session: Any,
+ repo_id: str,
+) -> None:
+ """Persist all outputs from a :class:`PipelineResult` into the database.
+
+ Parameters
+ ----------
+ result:
+ A ``PipelineResult`` from ``run_pipeline()``.
+ session:
+ An active SQLAlchemy ``AsyncSession`` (caller manages commit/rollback).
+ repo_id:
+ The repository ID to associate all records with.
+
+ Note
+ ----
+ FTS indexing is intentionally excluded here — callers must do it after
+ this session closes to avoid SQLite write-lock conflicts.
+
+ This function mutates ``sym.file_path`` on parsed-file symbols that
+ lack one. Callers should treat *result* as consumed after this call.
+ """
+ from repowise.core.persistence import (
+ batch_upsert_graph_edges,
+ batch_upsert_graph_nodes,
+ batch_upsert_symbols,
+ upsert_page_from_generated,
+ )
+ from repowise.core.persistence.crud import (
+ bulk_upsert_decisions,
+ save_dead_code_findings,
+ upsert_git_metadata_bulk,
+ )
+
+ # ---- Pages (if generated) -----------------------------------------------
+ if result.generated_pages:
+ for page in result.generated_pages:
+ await upsert_page_from_generated(session, page, repo_id)
+
+ # ---- Graph nodes ---------------------------------------------------------
+ graph = result.graph_builder.graph()
+ pr = result.graph_builder.pagerank()
+ bc = result.graph_builder.betweenness_centrality()
+ cd = result.graph_builder.community_detection()
+
+ nodes = []
+ for node_path in graph.nodes:
+ data = graph.nodes[node_path]
+ nodes.append(
+ {
+ "node_id": node_path,
+ "symbol_count": data.get("symbol_count", 0),
+ "has_error": data.get("has_error", False),
+ "is_test": data.get("is_test", False),
+ "is_entry_point": data.get("is_entry_point", False),
+ "language": data.get("language", "unknown"),
+ "pagerank": pr.get(node_path, 0.0),
+ "betweenness": bc.get(node_path, 0.0),
+ "community_id": cd.get(node_path, 0),
+ }
+ )
+ if nodes:
+ await batch_upsert_graph_nodes(session, repo_id, nodes)
+
+ # ---- Graph edges ---------------------------------------------------------
+ edges = []
+ for u, v, data in graph.edges(data=True):
+ edges.append(
+ {
+ "source_node_id": u,
+ "target_node_id": v,
+ "imported_names_json": json.dumps(data.get("imported_names", [])),
+ "edge_type": data.get("edge_type", "imports"),
+ }
+ )
+ if edges:
+ await batch_upsert_graph_edges(session, repo_id, edges)
+
+ # ---- Symbols -------------------------------------------------------------
+ # NOTE: This mutates sym.file_path on the caller's PipelineResult objects.
+ # The guard prevents double-set on retries, but callers should treat the
+ # result as consumed after this call.
+ all_symbols = []
+ for pf in result.parsed_files:
+ for sym in pf.symbols:
+ if not getattr(sym, "file_path", None):
+ sym.file_path = pf.file_info.path
+ all_symbols.append(sym)
+ if all_symbols:
+ await batch_upsert_symbols(session, repo_id, all_symbols)
+
+ # ---- Git metadata --------------------------------------------------------
+ if result.git_metadata_list:
+ await upsert_git_metadata_bulk(session, repo_id, result.git_metadata_list)
+
+ # ---- Dead code findings --------------------------------------------------
+ if result.dead_code_report and result.dead_code_report.findings:
+ await save_dead_code_findings(session, repo_id, result.dead_code_report.findings)
+
+ # ---- Decision records ----------------------------------------------------
+ if result.decision_report and result.decision_report.decisions:
+ await bulk_upsert_decisions(
+ session,
+ repo_id,
+ [dataclasses.asdict(d) for d in result.decision_report.decisions],
+ )
+
+ logger.info(
+ "pipeline_result_persisted",
+ repo_id=repo_id,
+ pages=len(result.generated_pages) if result.generated_pages else 0,
+ graph_nodes=len(nodes),
+ symbols=len(all_symbols),
+ git_files=len(result.git_metadata_list),
+ )
diff --git a/packages/server/src/repowise/server/app.py b/packages/server/src/repowise/server/app.py
index 44cd2c8d2..ddefcda4c 100644
--- a/packages/server/src/repowise/server/app.py
+++ b/packages/server/src/repowise/server/app.py
@@ -19,6 +19,7 @@ from fastapi import FastAPI, Request
from repowise.core.persistence.database import (
create_engine,
create_session_factory,
+ get_session,
init_db,
resolve_db_url,
)
@@ -81,6 +82,30 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
await init_db(engine)
session_factory = create_session_factory(engine)
+ # Reset any jobs left in "running" state from a previous server instance
+ # (crash or restart) — they can never complete now.
+ # Note: with multi-worker deployments this is a best-effort race; the
+ # try/except prevents a SQLite lock error from crashing startup.
+ try:
+ from sqlalchemy import update as sa_update
+ from repowise.core.persistence.models import GenerationJob
+ from datetime import datetime, UTC as _UTC
+
+ async with get_session(session_factory) as session:
+ stale_result = await session.execute(
+ sa_update(GenerationJob)
+ .where(GenerationJob.status == "running")
+ .values(
+ status="failed",
+ error_message="Server restarted — job interrupted",
+ finished_at=datetime.now(_UTC),
+ )
+ )
+ if stale_result.rowcount:
+ logger.warning("reset_stale_jobs", extra={"count": stale_result.rowcount})
+ except Exception as exc:
+ logger.warning("stale_job_reset_failed", extra={"error": str(exc)})
+
# Full-text search
fts = FullTextSearch(engine)
await fts.ensure_index()
@@ -99,6 +124,7 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
app.state.fts = fts
app.state.vector_store = vector_store
app.state.scheduler = scheduler
+ app.state.background_tasks: set = set() # Strong refs to prevent GC of asyncio tasks
# Initialize chat tool state (bridges FastAPI state to MCP tool globals)
from repowise.server.chat_tools import init_tool_state
diff --git a/packages/server/src/repowise/server/job_executor.py b/packages/server/src/repowise/server/job_executor.py
new file mode 100644
index 000000000..787fd2344
--- /dev/null
+++ b/packages/server/src/repowise/server/job_executor.py
@@ -0,0 +1,268 @@
+"""Background job executor for server-triggered pipeline runs.
+
+Bridges the gap between the REST endpoints (which create pending jobs)
+and the core pipeline (which does the actual work). Uses the same
+``run_pipeline()`` and ``persist_pipeline_result()`` as the CLI — zero
+duplication.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+import structlog
+
+from repowise.core.persistence.crud import (
+ get_generation_job,
+ get_repository,
+ update_job_status,
+)
+from repowise.core.persistence.database import get_session
+from repowise.core.pipeline import persist_pipeline_result, run_pipeline
+
+logger = structlog.get_logger(__name__)
+
+# Phase → numeric level mapping for job.current_level
+_PHASE_LEVELS = {
+ "traverse": 0,
+ "parse": 0,
+ "graph": 0,
+ "git": 0,
+ "co_change": 0,
+ "dead_code": 1,
+ "decisions": 1,
+ "generation": 2,
+}
+
+
+class JobProgressCallback:
+ """ProgressCallback that writes progress to the GenerationJob record.
+
+ The SSE stream endpoint polls the job table, so updating the record
+ is sufficient to push live progress to the frontend.
+ """
+
+ def __init__(self, job_id: str, session_factory: Any) -> None:
+ self._job_id = job_id
+ self._session_factory = session_factory
+ self._completed = 0
+ self._total: int | None = None
+ self._phase = ""
+ self._pending_flush = 0
+ self._stopped = False
+ # Track in-flight update tasks to cancel before final status write
+ self._pending_tasks: set[asyncio.Task] = set() # type: ignore[type-arg]
+ # Batch DB writes: flush every N items to avoid per-item overhead
+ self._flush_interval = 5
+
+ def on_phase_start(self, phase: str, total: int | None) -> None:
+ self._phase = phase
+ # Reset per-phase counters so the bar shows progress within the current phase
+ self._completed = 0
+ self._total = total
+ self._pending_flush = 0
+ self._sync_job_status() # Flush immediately so the label updates
+ logger.info("job_phase_start", job_id=self._job_id, phase=phase, total=total)
+
+ def on_item_done(self, phase: str) -> None:
+ self._completed += 1
+ self._pending_flush += 1
+ if self._pending_flush >= self._flush_interval:
+ self._pending_flush = 0
+ self._sync_job_status()
+
+ def on_message(self, level: str, text: str) -> None:
+ getattr(logger, level, logger.info)(
+ text, job_id=self._job_id, phase=self._phase
+ )
+
+ def _sync_job_status(self) -> None:
+ """Fire-and-forget progress update in the current event loop.
+
+ Tracks task references to allow cancellation before final status.
+ """
+ if self._stopped:
+ return
+
+ try:
+ loop = asyncio.get_running_loop()
+ t = loop.create_task(self._async_update())
+ self._pending_tasks.add(t)
+ t.add_done_callback(self._pending_tasks.discard)
+ except RuntimeError:
+ pass # No event loop — skip the update
+
+ async def drain_and_stop(self) -> None:
+ """Wait for in-flight progress updates to finish, then prevent new ones.
+
+ Must be called before writing the final job status to avoid a race
+ where a late progress update overwrites ``completed`` with ``running``.
+
+ We do NOT cancel tasks — a cancelled task whose DB write is already
+ past the ``await`` will leave the session in a dirty state. Instead
+ we set the stopped flag (preventing new tasks) and let existing ones
+ finish naturally.
+ """
+ self._stopped = True
+ if self._pending_tasks:
+ await asyncio.gather(*self._pending_tasks, return_exceptions=True)
+ self._pending_tasks.clear()
+
+ async def _async_update(self) -> None:
+ try:
+ async with get_session(self._session_factory) as session:
+ await update_job_status(
+ session,
+ self._job_id,
+ "running",
+ completed_pages=self._completed,
+ total_pages=self._total,
+ current_level=_PHASE_LEVELS.get(self._phase, 0),
+ )
+ except Exception:
+ logger.debug("progress_update_failed", job_id=self._job_id, exc_info=True)
+
+
+async def execute_job(job_id: str, app_state: Any) -> None:
+ """Execute a pending pipeline job in the background.
+
+ This is the single entry point called by the endpoint via
+ ``asyncio.create_task()``. It:
+
+ 1. Marks the job as ``running``
+ 2. Resolves the LLM provider from server config
+ 3. Runs ``run_pipeline()``
+ 4. Persists all results via ``persist_pipeline_result()``
+ 5. Marks the job as ``completed`` (or ``failed`` on error)
+ """
+ session_factory = app_state.session_factory
+ fts = app_state.fts
+ vector_store = app_state.vector_store
+ start = time.monotonic()
+ progress: JobProgressCallback | None = None
+
+ try:
+ # ---- Fetch job + repo metadata ------------------------------------
+ async with get_session(session_factory) as session:
+ job = await get_generation_job(session, job_id)
+ if job is None:
+ logger.error("job_not_found", job_id=job_id)
+ return
+
+ repo = await get_repository(session, job.repository_id)
+ if repo is None:
+ logger.error("repo_not_found", job_id=job_id, repo_id=job.repository_id)
+ await update_job_status(session, job_id, "failed", error_message="Repository not found")
+ return
+
+ repo_path = repo.local_path
+ repo_id = repo.id
+ config = json.loads(job.config_json) if job.config_json else {}
+ is_full_resync = config.get("mode") == "full_resync"
+
+ # Mark running
+ await update_job_status(session, job_id, "running")
+
+ logger.info(
+ "job_started",
+ job_id=job_id,
+ repo_path=repo_path,
+ mode="full_resync" if is_full_resync else "sync",
+ )
+
+ # ---- Resolve LLM provider -----------------------------------------
+ llm_client = None
+ try:
+ from repowise.server.provider_config import get_chat_provider_instance
+
+ llm_client = get_chat_provider_instance()
+ except Exception as exc:
+ logger.warning("no_provider_configured", error=str(exc))
+ # Continue without LLM — ingestion + analysis still work
+
+ # ---- Run pipeline --------------------------------------------------
+ progress = JobProgressCallback(job_id, session_factory)
+
+ result = await run_pipeline(
+ Path(repo_path),
+ generate_docs=is_full_resync and llm_client is not None,
+ llm_client=llm_client,
+ vector_store=vector_store,
+ progress=progress,
+ )
+
+ # ---- Persist results -----------------------------------------------
+ async with get_session(session_factory) as session:
+ await persist_pipeline_result(result, session, repo_id)
+
+ # FTS indexing runs after session closes to avoid SQLite write conflicts
+ if fts is not None and result.generated_pages:
+ for page in result.generated_pages:
+ await fts.index(page.page_id, page.title, page.content)
+
+ # ---- Mark completed ------------------------------------------------
+ # Stop progress updates before writing final status to prevent a
+ # late "running" update from overwriting "completed".
+ await progress.drain_and_stop()
+
+ elapsed = time.monotonic() - start
+ total_input = sum(p.input_tokens for p in (result.generated_pages or []))
+ total_output = sum(p.output_tokens for p in (result.generated_pages or []))
+
+ async with get_session(session_factory) as session:
+ job = await get_generation_job(session, job_id)
+ # Store summary in config for the frontend to display
+ final_config = config.copy()
+ final_config.update(
+ {
+ "total_input_tokens": total_input,
+ "total_output_tokens": total_output,
+ "elapsed_seconds": round(elapsed, 1),
+ "file_count": result.file_count,
+ "symbol_count": result.symbol_count,
+ "pages_generated": len(result.generated_pages) if result.generated_pages else 0,
+ }
+ )
+ if job is not None:
+ job.config_json = json.dumps(final_config)
+
+ await update_job_status(
+ session,
+ job_id,
+ "completed",
+ completed_pages=len(result.generated_pages) if result.generated_pages else result.file_count,
+ total_pages=len(result.generated_pages) if result.generated_pages else result.file_count,
+ )
+
+ logger.info(
+ "job_completed",
+ job_id=job_id,
+ elapsed=round(elapsed, 1),
+ files=result.file_count,
+ symbols=result.symbol_count,
+ pages=len(result.generated_pages) if result.generated_pages else 0,
+ )
+
+ except Exception as exc:
+ logger.exception("job_failed", job_id=job_id, error=str(exc))
+ # Drain progress updates before writing final "failed" status to prevent
+ # a late fire-and-forget progress update from overwriting it with "running".
+ if progress is not None:
+ try:
+ await progress.drain_and_stop()
+ except Exception:
+ logger.debug("drain_failed_on_error_path", job_id=job_id, exc_info=True)
+ try:
+ async with get_session(session_factory) as session:
+ await update_job_status(
+ session,
+ job_id,
+ "failed",
+ error_message=str(exc)[:500],
+ )
+ except Exception:
+ logger.exception("job_status_update_failed", job_id=job_id)
diff --git a/packages/server/src/repowise/server/routers/repos.py b/packages/server/src/repowise/server/routers/repos.py
index 9788a7ab0..d2a1ecd06 100644
--- a/packages/server/src/repowise/server/routers/repos.py
+++ b/packages/server/src/repowise/server/routers/repos.py
@@ -2,15 +2,27 @@
from __future__ import annotations
+import asyncio
+import logging
+
from sqlalchemy import func, select
from sqlalchemy.ext.asyncio import AsyncSession
-from fastapi import APIRouter, Depends, HTTPException
+from fastapi import APIRouter, Depends, HTTPException, Request
from repowise.core.persistence import crud
-from repowise.core.persistence.models import DeadCodeFinding, GraphNode, Page, Repository
+from repowise.core.persistence.models import (
+ DeadCodeFinding,
+ GenerationJob,
+ GraphNode,
+ Page,
+ Repository,
+)
from repowise.server.deps import get_db_session, verify_api_key
+from repowise.server.job_executor import execute_job
from repowise.server.schemas import RepoCreate, RepoResponse, RepoStatsResponse, RepoUpdate
+logger = logging.getLogger(__name__)
+
router = APIRouter(
prefix="/api/repos",
tags=["repos"],
@@ -138,42 +150,93 @@ async def get_repo_stats(
@router.post("/{repo_id}/sync", status_code=202)
async def sync_repo(
repo_id: str,
+ request: Request,
session: AsyncSession = Depends(get_db_session), # noqa: B008
) -> dict:
"""Trigger an incremental documentation sync for a repository.
- Creates a pending generation job and returns its ID.
- The actual sync runs asynchronously.
+ Creates a generation job, launches the pipeline in the background,
+ and returns immediately with the job ID.
"""
repo = await crud.get_repository(session, repo_id)
if repo is None:
raise HTTPException(status_code=404, detail="Repository not found")
+ # Prevent concurrent pipeline runs on the same repo
+ active = await session.execute(
+ select(GenerationJob.id)
+ .where(GenerationJob.repository_id == repo_id)
+ .where(GenerationJob.status.in_(["pending", "running"]))
+ .limit(1)
+ )
+ if active.scalar_one_or_none() is not None:
+ raise HTTPException(status_code=409, detail="A sync job is already in progress for this repository")
+
job = await crud.upsert_generation_job(
session,
repository_id=repo_id,
status="pending",
)
+ # Commit (not just flush) so the background task's separate session can
+ # see the job row. SQLite WAL isolation hides uncommitted rows from
+ # other connections, so flush() alone is not sufficient.
+ await session.commit()
+ _launch_job_task(request, job.id)
return {"job_id": job.id, "status": "accepted"}
@router.post("/{repo_id}/full-resync", status_code=202)
async def full_resync(
repo_id: str,
+ request: Request,
session: AsyncSession = Depends(get_db_session), # noqa: B008
) -> dict:
"""Trigger a full re-generation of all documentation.
- Creates a pending generation job and returns its ID.
+ Creates a generation job, launches the pipeline in the background,
+ and returns immediately with the job ID.
"""
repo = await crud.get_repository(session, repo_id)
if repo is None:
raise HTTPException(status_code=404, detail="Repository not found")
+ # Prevent concurrent pipeline runs on the same repo
+ active = await session.execute(
+ select(GenerationJob.id)
+ .where(GenerationJob.repository_id == repo_id)
+ .where(GenerationJob.status.in_(["pending", "running"]))
+ .limit(1)
+ )
+ if active.scalar_one_or_none() is not None:
+ raise HTTPException(status_code=409, detail="A sync job is already in progress for this repository")
+
job = await crud.upsert_generation_job(
session,
repository_id=repo_id,
status="pending",
config={"mode": "full_resync"},
)
+ # Commit (not just flush) so the background task's separate session can
+ # see the job row. See sync_repo comment for rationale.
+ await session.commit()
+ _launch_job_task(request, job.id)
return {"job_id": job.id, "status": "accepted"}
+
+
+def _launch_job_task(request: Request, job_id: str) -> None:
+ """Launch a background job task with proper lifecycle management.
+
+ Stores a strong reference in ``app.state.background_tasks`` to prevent
+ garbage collection, and removes it when the task finishes. Exceptions
+ are logged instead of silently swallowed.
+ """
+ task = asyncio.create_task(execute_job(job_id, request.app.state), name=f"job-{job_id}")
+ bg_tasks: set[asyncio.Task] = request.app.state.background_tasks # type: ignore[assignment]
+ bg_tasks.add(task)
+
+ def _on_done(t: asyncio.Task) -> None:
+ bg_tasks.discard(t)
+ if not t.cancelled() and t.exception() is not None:
+ logger.error("background_job_failed", exc_info=t.exception())
+
+ task.add_done_callback(_on_done)
diff --git a/packages/web/src/app/page.tsx b/packages/web/src/app/page.tsx
index bebe9b5e7..e1b30b116 100644
--- a/packages/web/src/app/page.tsx
+++ b/packages/web/src/app/page.tsx
@@ -37,7 +37,7 @@ export default async function DashboardPage() {
// If there's exactly one repo, go straight to it — no need for a dashboard.
if (repoList.length === 1) {
- redirect(`/repos/${repoList[0].id}`);
+ redirect(`/repos/${repoList[0].id}/overview`);
}
// Aggregate stats across all repos
diff --git a/packages/web/src/app/repos/[id]/layout.tsx b/packages/web/src/app/repos/[id]/layout.tsx
index 14012db9b..23b447cf9 100644
--- a/packages/web/src/app/repos/[id]/layout.tsx
+++ b/packages/web/src/app/repos/[id]/layout.tsx
@@ -1,5 +1,6 @@
import { redirect } from "next/navigation";
import { getRepo } from "@/lib/api/repos";
+import { ActiveJobBanner } from "@/components/dashboard/active-job-banner";
interface RepoLayoutProps {
children: React.ReactNode;
@@ -15,5 +16,10 @@ export default async function RepoLayout({ children, params }: RepoLayoutProps)
// project). Redirect to the dashboard so the user sees what's available.
redirect("/");
}
- return <>{children}</>;
+ return (
+ <>
+ <ActiveJobBanner repoId={id} />
+ {children}
+ </>
+ );
}
diff --git a/packages/web/src/app/repos/[id]/overview/loading.tsx b/packages/web/src/app/repos/[id]/overview/loading.tsx
new file mode 100644
index 000000000..a280cd429
--- /dev/null
+++ b/packages/web/src/app/repos/[id]/overview/loading.tsx
@@ -0,0 +1,78 @@
+import { Skeleton } from "@/components/ui/skeleton";
+import { Card, CardContent } from "@/components/ui/card";
+
+export default function OverviewLoading() {
+ return (
+ <div className="p-4 sm:p-6 space-y-6 max-w-[1600px]">
+ {/* Hero */}
+ <div className="flex flex-col sm:flex-row items-start gap-6">
+ <Skeleton className="h-[160px] w-[160px] rounded-full shrink-0" />
+ <div className="flex-1 space-y-3 w-full">
+ <div className="space-y-2">
+ <Skeleton className="h-6 w-48" />
+ <Skeleton className="h-3 w-72" />
+ </div>
+ <div className="flex gap-2">
+ <Skeleton className="h-8 w-20" />
+ <Skeleton className="h-8 w-28" />
+ <Skeleton className="h-8 w-32" />
+ </div>
+ <div className="grid grid-cols-2 gap-2 sm:grid-cols-5">
+ {Array.from({ length: 5 }).map((_, i) => (
+ <Card key={i}>
+ <CardContent className="p-3 space-y-2">
+ <Skeleton className="h-3 w-12" />
+ <Skeleton className="h-6 w-16" />
+ </CardContent>
+ </Card>
+ ))}
+ </div>
+ </div>
+ </div>
+
+ {/* Grid */}
+ <div className="grid grid-cols-1 gap-4 lg:grid-cols-3">
+ <div className="space-y-4 lg:col-span-2">
+ <Card>
+ <CardContent className="p-6 space-y-3">
+ <Skeleton className="h-4 w-36" />
+ {Array.from({ length: 4 }).map((_, i) => (
+ <Skeleton key={i} className="h-8 w-full" />
+ ))}
+ </CardContent>
+ </Card>
+ <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+ <Card>
+ <CardContent className="p-6 space-y-2">
+ <Skeleton className="h-4 w-28" />
+ {Array.from({ length: 5 }).map((_, i) => (
+ <Skeleton key={i} className="h-5 w-full" />
+ ))}
+ </CardContent>
+ </Card>
+ <Card>
+ <CardContent className="p-6 space-y-2">
+ <Skeleton className="h-4 w-32" />
+ {Array.from({ length: 5 }).map((_, i) => (
+ <Skeleton key={i} className="h-5 w-full" />
+ ))}
+ </CardContent>
+ </Card>
+ </div>
+ </div>
+ <div className="space-y-4">
+ <Card>
+ <CardContent className="p-6">
+ <Skeleton className="h-[120px] w-[120px] rounded-full mx-auto" />
+ </CardContent>
+ </Card>
+ <Card>
+ <CardContent className="p-6">
+ <Skeleton className="h-[220px] w-full" />
+ </CardContent>
+ </Card>
+ </div>
+ </div>
+ </div>
+ );
+}
diff --git a/packages/web/src/app/repos/[id]/overview/page.tsx b/packages/web/src/app/repos/[id]/overview/page.tsx
new file mode 100644
index 000000000..574e2cf9f
--- /dev/null
+++ b/packages/web/src/app/repos/[id]/overview/page.tsx
@@ -0,0 +1,303 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { Hash, Activity } from "lucide-react";
+import { getRepo, getRepoStats } from "@/lib/api/repos";
+import { getGitSummary, getHotspots, getOwnership } from "@/lib/api/git";
+import { getDeadCodeSummary, listDeadCode } from "@/lib/api/dead-code";
+import { listDecisions, getDecisionHealth } from "@/lib/api/decisions";
+import { getGraph, getModuleGraph } from "@/lib/api/graph";
+import { getProviders } from "@/lib/api/providers";
+import { listJobs } from "@/lib/api/jobs";
+import { Badge } from "@/components/ui/badge";
+import { StatCard } from "@/components/shared/stat-card";
+import { HealthScoreRing } from "@/components/dashboard/health-score-ring";
+import { AttentionPanel } from "@/components/dashboard/attention-panel";
+import { QuickActions } from "@/components/dashboard/quick-actions";
+import { OwnershipTreemap } from "@/components/dashboard/ownership-treemap";
+import { LanguageDonut } from "@/components/dashboard/language-donut";
+import { computeHealthScore, buildAttentionItems, aggregateLanguages } from "@/lib/utils/health-score";
+import { HotspotsMini } from "@/components/dashboard/hotspots-mini";
+import { DecisionsTimeline } from "@/components/dashboard/decisions-timeline";
+import { ModuleMinimap } from "@/components/dashboard/module-minimap";
+import { BusFactorPanel } from "@/components/git/bus-factor-panel";
+import { ChurnHistogram } from "@/components/git/churn-histogram";
+import { CommitCategoryDonut } from "@/components/git/commit-category-donut";
+import { CommitCategorySparkline } from "@/components/git/commit-category-sparkline";
+import { OwnershipTreemap as OwnershipTreemapGit } from "@/components/git/ownership-treemap";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { formatNumber } from "@/lib/utils/format";
+import type {
+ RepoStatsResponse,
+ GitSummaryResponse,
+ HotspotResponse,
+ OwnershipEntry,
+ DeadCodeSummaryResponse,
+ DecisionRecordResponse,
+ DecisionHealthResponse,
+ GraphExportResponse,
+ ModuleGraphResponse,
+} from "@/lib/api/types";
+
+export const metadata: Metadata = { title: "Overview" };
+
+interface Props {
+ params: Promise<{ id: string }>;
+}
+
+// Each fetch wrapped to return null on failure — the dashboard degrades gracefully
+async function safeFetch<T>(fn: () => Promise<T>): Promise<T | null> {
+ try {
+ return await fn();
+ } catch {
+ return null;
+ }
+}
+
+export default async function OverviewPage({ params }: Props) {
+ const { id } = await params;
+
+ const repo = await safeFetch(() => getRepo(id));
+ if (!repo) notFound();
+
+ // Fetch all data in parallel — each independently failable
+ const [stats, gitSummary, hotspots, ownership, deadCodeSummary, deadCodeSafe, decisions, decisionHealth, graph, moduleGraph, providers, completedJobs] =
+ await Promise.all([
+ safeFetch(() => getRepoStats(id)),
+ safeFetch(() => getGitSummary(id)),
+ safeFetch(() => getHotspots(id, 50)),
+ safeFetch(() => getOwnership(id, "module")),
+ safeFetch(() => getDeadCodeSummary(id)),
+ safeFetch(() => listDeadCode(id, { safe_only: true, status: "active", limit: 50 })),
+ safeFetch(() => listDecisions(id, { limit: 10 })),
+ safeFetch(() => getDecisionHealth(id)),
+ safeFetch(() => getGraph(id)),
+ safeFetch(() => getModuleGraph(id)),
+ safeFetch(() => getProviders()),
+ safeFetch(() => listJobs({ repo_id: id, limit: 20, status: "completed" })),
+ ]);
+
+ // Find timestamps for last sync and last full re-index from completed jobs
+ const lastSyncJob = completedJobs?.find((j) => !j.config?.mode || j.config.mode === "sync");
+ const lastResyncJob = completedJobs?.find((j) => j.config?.mode === "full_resync");
+
+ // Compute health score
+ const siloCount = ownership?.filter((o) => o.is_silo).length ?? 0;
+ const healthScore = computeHealthScore({
+ docCoveragePct: stats?.doc_coverage_pct ?? 0,
+ freshnessScore: stats?.freshness_score ?? 0,
+ deadExportCount: stats?.dead_export_count ?? 0,
+ symbolCount: stats?.symbol_count ?? 1,
+ hotspotCount: gitSummary?.hotspot_count ?? 0,
+ totalFiles: gitSummary?.total_files ?? 1,
+ siloCount,
+ totalModules: ownership?.length ?? 1,
+ });
+
+ // Build attention items
+ const attentionItems = buildAttentionItems({
+ staleDecisions: decisionHealth?.stale_decisions ?? [],
+ proposedDecisions: decisionHealth?.proposed_awaiting_review ?? [],
+ ungovernedHotspots: decisionHealth?.ungoverned_hotspots ?? [],
+ siloModules: ownership?.filter((o) => o.is_silo) ?? [],
+ deadCodeSafe: deadCodeSafe ?? [],
+ });
+
+ // Aggregate language distribution from graph nodes
+ const langDistribution = graph ? aggregateLanguages(graph.nodes) : {};
+
+ return (
+ <div className="p-4 sm:p-6 space-y-6 max-w-[1600px]">
+ {/* ── Hero: Health Score + Repo Info + Quick Actions ── */}
+ <div className="flex flex-col sm:flex-row items-start gap-6">
+ <HealthScoreRing score={healthScore} />
+
+ <div className="flex-1 min-w-0 space-y-3">
+ <div>
+ <div className="flex items-center gap-2">
+ <h1 className="text-xl font-semibold text-[var(--color-text-primary)] truncate">
+ {repo.name}
+ </h1>
+ {repo.head_commit && (
+ <Badge variant="outline" className="text-[10px] h-5 shrink-0">
+ <Hash className="h-2.5 w-2.5" />
+ {repo.head_commit.slice(0, 7)}
+ </Badge>
+ )}
+ <Badge variant="outline" className="text-[10px] h-5 shrink-0">
+ {repo.default_branch}
+ </Badge>
+ </div>
+ <p className="text-xs font-mono text-[var(--color-text-tertiary)] truncate mt-0.5">
+ {repo.local_path}
+ </p>
+ </div>
+
+ {/* Quick actions */}
+ <QuickActions
+ repoId={id}
+ repoName={repo.name}
+ pageCount={stats?.file_count ?? 0}
+ modelName={providers?.active.model ?? ""}
+ lastSyncAt={lastSyncJob?.finished_at ?? null}
+ lastResyncAt={lastResyncJob?.finished_at ?? null}
+ />
+
+ {/* Key metrics strip */}
+ <div className="grid grid-cols-2 gap-2 sm:grid-cols-5">
+ <StatCard
+ label="Files"
+ value={stats ? formatNumber(stats.file_count) : "—"}
+ className="!p-0 [&>div]:!p-3"
+ />
+ <StatCard
+ label="Symbols"
+ value={stats ? formatNumber(stats.symbol_count) : "—"}
+ className="!p-0 [&>div]:!p-3"
+ />
+ <StatCard
+ label="Entry Points"
+ value={stats ? formatNumber(stats.entry_point_count) : "—"}
+ className="!p-0 [&>div]:!p-3"
+ />
+ <StatCard
+ label="Doc Coverage"
+ value={stats ? `${Math.round(stats.doc_coverage_pct)}%` : "—"}
+ className="!p-0 [&>div]:!p-3"
+ />
+ <StatCard
+ label="Dead Exports"
+ value={stats ? formatNumber(stats.dead_export_count) : "—"}
+ description={
+ deadCodeSummary
+ ? `${formatNumber(deadCodeSummary.deletable_lines)} deletable lines`
+ : undefined
+ }
+ className="!p-0 [&>div]:!p-3"
+ />
+ </div>
+ </div>
+ </div>
+
+ {/* ── Main Grid ── */}
+ <div className="grid grid-cols-1 gap-4 lg:grid-cols-3">
+ {/* Left column — Attention + Hotspots */}
+ <div className="space-y-4 lg:col-span-2">
+ <AttentionPanel items={attentionItems} repoId={id} />
+ <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+ <HotspotsMini hotspots={hotspots ?? []} repoId={id} />
+ <DecisionsTimeline
+ decisions={
+ decisions
+ ? [...decisions].sort(
+ (a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime()
+ )
+ : []
+ }
+ repoId={id}
+ />
+ </div>
+ </div>
+
+ {/* Right column — Visualizations */}
+ <div className="space-y-4">
+ <LanguageDonut distribution={langDistribution} />
+ {ownership && ownership.length > 0 && (
+ <OwnershipTreemap entries={ownership} />
+ )}
+ </div>
+ </div>
+
+ {/* ── Git Insights ── */}
+ {hotspots && hotspots.length > 0 && (() => {
+ const aggregatedCategories: Record<string, number> = {};
+ for (const h of hotspots) {
+ for (const [cat, count] of Object.entries(h.commit_categories ?? {})) {
+ aggregatedCategories[cat] = (aggregatedCategories[cat] || 0) + count;
+ }
+ }
+ const hasCategories = Object.values(aggregatedCategories).some((v) => v > 0);
+
+ return (
+ <div className="space-y-4">
+ <h2 className="text-sm font-medium text-[var(--color-text-secondary)] uppercase tracking-wider">
+ Git Insights
+ </h2>
+
+ {/* Commit category sparkline (full width) */}
+ {hasCategories && (
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm font-medium">Commit Activity</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <CommitCategorySparkline categories={aggregatedCategories} />
+ <div className="flex items-center gap-4 mt-2 text-[10px] text-[var(--color-text-tertiary)]">
+ <span className="flex items-center gap-1"><span className="inline-block h-2 w-2 rounded-sm" style={{ background: "#5b9cf6" }} /> Feature</span>
+ <span className="flex items-center gap-1"><span className="inline-block h-2 w-2 rounded-sm" style={{ background: "#ef4444" }} /> Fix</span>
+ <span className="flex items-center gap-1"><span className="inline-block h-2 w-2 rounded-sm" style={{ background: "#a855f7" }} /> Refactor</span>
+ <span className="flex items-center gap-1"><span className="inline-block h-2 w-2 rounded-sm" style={{ background: "#f59520" }} /> Dependency</span>
+ </div>
+ </CardContent>
+ </Card>
+ )}
+
+ <div className="grid grid-cols-1 gap-4 lg:grid-cols-3">
+ {/* Churn Histogram */}
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm font-medium">Churn Distribution</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <ChurnHistogram hotspots={hotspots} />
+ </CardContent>
+ </Card>
+
+ {/* Commit Category Donut */}
+ {hasCategories && (
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm font-medium">Commit Categories</CardTitle>
+ </CardHeader>
+ <CardContent className="flex items-center justify-center">
+ <CommitCategoryDonut categories={aggregatedCategories} />
+ </CardContent>
+ </Card>
+ )}
+
+ {/* Bus Factor */}
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm font-medium">Bus Factor</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <BusFactorPanel hotspots={hotspots} />
+ </CardContent>
+ </Card>
+ </div>
+
+ {/* Ownership Treemap (git-level, file granularity) */}
+ {ownership && ownership.length > 0 && (
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm font-medium">Ownership Map</CardTitle>
+ </CardHeader>
+ <CardContent>
+ <OwnershipTreemapGit entries={ownership} />
+ </CardContent>
+ </Card>
+ )}
+ </div>
+ );
+ })()}
+
+ {/* ── Module Architecture Map (full width) ── */}
+ {moduleGraph && moduleGraph.nodes.length > 0 && (
+ <ModuleMinimap
+ nodes={moduleGraph.nodes}
+ edges={moduleGraph.edges}
+ repoId={id}
+ />
+ )}
+ </div>
+ );
+}
diff --git a/packages/web/src/components/dashboard/active-job-banner.tsx b/packages/web/src/components/dashboard/active-job-banner.tsx
new file mode 100644
index 000000000..474d064a4
--- /dev/null
+++ b/packages/web/src/components/dashboard/active-job-banner.tsx
@@ -0,0 +1,104 @@
+"use client";
+
+import useSWR from "swr";
+import Link from "next/link";
+import { Loader2, CheckCircle, XCircle, ExternalLink } from "lucide-react";
+import { Progress } from "@/components/ui/progress";
+import { listJobs } from "@/lib/api/jobs";
+import { formatNumber, formatRelativeTime } from "@/lib/utils/format";
+import type { JobResponse } from "@/lib/api/types";
+
+interface ActiveJobBannerProps {
+ repoId: string;
+}
+
+export function ActiveJobBanner({ repoId }: ActiveJobBannerProps) {
+ const { data: jobs } = useSWR<JobResponse[]>(
+ `/api/jobs?repo_id=${repoId}&limit=1`,
+ () => listJobs({ repo_id: repoId, limit: 1 }),
+ { refreshInterval: (data) => {
+ const j = data?.[0];
+ if (j?.status === "running") return 5000; // poll faster when running
+ return 30000; // slow poll otherwise
+ }},
+ );
+
+ const job = jobs?.[0];
+ if (!job) return null;
+
+ const isRunning = job.status === "running";
+ const isDone = job.status === "completed";
+ const isFailed = job.status === "failed";
+
+ // Don't show pending jobs (they may never start) or old terminal states
+ if (job.status === "pending") return null;
+ if (!isRunning) {
+ const finishedAt = job.finished_at ? new Date(job.finished_at).getTime() : 0;
+ const age = Date.now() - finishedAt;
+ if (age > 60_000) return null;
+ }
+
+ const progress = job.total_pages > 0
+ ? Math.min(100, Math.round((job.completed_pages / job.total_pages) * 100))
+ : 0;
+
+ const mode = (job.config?.mode as string) ?? "sync";
+ const label = mode === "full_resync" ? "Full Re-index" : "Sync";
+
+ const PHASE_LABELS: Record<number, string> = {
+ 0: "Indexing",
+ 1: "Analysing",
+ 2: "Generating docs",
+ };
+ const phaseLabel = PHASE_LABELS[job.current_level ?? 0] ?? "Processing";
+
+ return (
+ <div className="px-4 py-2 border-b border-[var(--color-border-default)] bg-[var(--color-bg-inset)]">
+ <div className="flex items-center gap-3">
+ {/* Status icon */}
+ {isRunning && <Loader2 className="h-3.5 w-3.5 animate-spin text-[var(--color-accent-primary)] shrink-0" />}
+ {isDone && <CheckCircle className="h-3.5 w-3.5 text-[var(--color-success)] shrink-0" />}
+ {isFailed && <XCircle className="h-3.5 w-3.5 text-[var(--color-error)] shrink-0" />}
+
+ {/* Label */}
+ <span className="text-xs text-[var(--color-text-secondary)]">
+ {isRunning && `${label} · ${phaseLabel}…`}
+ {isDone && `${label} complete`}
+ {isFailed && `${label} failed`}
+ </span>
+
+ {/* Progress bar (running only) */}
+ {isRunning && (
+ <div className="flex-1 max-w-[200px]">
+ <Progress value={progress} className="h-1.5" />
+ </div>
+ )}
+
+ {/* Stats */}
+ <span className="text-[10px] text-[var(--color-text-tertiary)] tabular-nums">
+ {isRunning && job.total_pages > 0 && `${formatNumber(job.completed_pages)}/${formatNumber(job.total_pages)}`}
+ {isDone && (
+ <>
+ {formatNumber(job.completed_pages)} pages
+ {job.config?.total_input_tokens && (
+ <> · {formatNumber(job.config.total_input_tokens as number)} tokens</>
+ )}
+ {job.finished_at && <> · {formatRelativeTime(job.finished_at)}</>}
+ </>
+ )}
+ {isFailed && (job.error_message ?? "Unknown error")}
+ </span>
+
+ {/* Link to overview for details */}
+ {isDone && job.completed_pages > 0 && (
+ <Link
+ href={`/repos/${repoId}/overview`}
+ className="text-[10px] text-[var(--color-accent-primary)] hover:underline flex items-center gap-0.5 shrink-0"
+ >
+ Details <ExternalLink className="h-2.5 w-2.5" />
+ </Link>
+ )}
+ </div>
+ </div>
+ );
+}
diff --git a/packages/web/src/components/dashboard/attention-panel.tsx b/packages/web/src/components/dashboard/attention-panel.tsx
new file mode 100644
index 000000000..8151693e9
--- /dev/null
+++ b/packages/web/src/components/dashboard/attention-panel.tsx
@@ -0,0 +1,123 @@
+import {
+ AlertTriangle,
+ Trash2,
+ Users,
+ FileWarning,
+ Lightbulb,
+} from "lucide-react";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Badge } from "@/components/ui/badge";
+
+import type { AttentionItem } from "@/lib/utils/health-score";
+export type { AttentionItem };
+
+const ICON_MAP = {
+ stale_decision: AlertTriangle,
+ knowledge_silo: Users,
+ ungoverned_hotspot: FileWarning,
+ dead_code: Trash2,
+ proposed_decision: Lightbulb,
+} as const;
+
+const SEVERITY_COLORS = {
+ high: "text-[var(--color-error)]",
+ medium: "text-[var(--color-warning)]",
+ low: "text-[var(--color-text-tertiary)]",
+} as const;
+
+const TYPE_LABELS = {
+ stale_decision: "Stale Decision",
+ knowledge_silo: "Knowledge Silo",
+ ungoverned_hotspot: "Ungoverned Hotspot",
+ dead_code: "Dead Code",
+ proposed_decision: "Needs Review",
+} as const;
+
+interface AttentionPanelProps {
+ items: AttentionItem[];
+ repoId: string;
+}
+
+export function AttentionPanel({ items, repoId }: AttentionPanelProps) {
+ if (items.length === 0) {
+ return (
+ <Card>
+ <CardContent className="p-6 text-center">
+ <p className="text-sm text-[var(--color-success)]">
+ No attention items — codebase looks healthy
+ </p>
+ </CardContent>
+ </Card>
+ );
+ }
+
+ return (
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm flex items-center justify-between">
+ <span className="flex items-center gap-2">
+ <AlertTriangle className="h-4 w-4 text-[var(--color-warning)]" />
+ Attention Needed
+ </span>
+ <Badge variant="outline" className="text-[10px] h-5 tabular-nums">
+ {items.length}
+ </Badge>
+ </CardTitle>
+ </CardHeader>
+ <CardContent className="pt-0">
+ <div className="space-y-1">
+ {items.slice(0, 8).map((item) => {
+ const Icon = ICON_MAP[item.type];
+ const href = item.href ?? getDefaultHref(item, repoId);
+ return (
+ <a
+ key={item.id}
+ href={href}
+ className="flex items-start gap-2.5 p-2 -mx-2 rounded-md hover:bg-[var(--color-bg-elevated)] transition-colors group"
+ >
+ <Icon
+ className={`h-3.5 w-3.5 mt-0.5 shrink-0 ${SEVERITY_COLORS[item.severity]}`}
+ />
+ <div className="min-w-0 flex-1">
+ <div className="flex items-center gap-2">
+ <span className="text-xs font-medium text-[var(--color-text-primary)] truncate group-hover:text-[var(--color-accent-primary)] transition-colors">
+ {item.title}
+ </span>
+ <span className="text-[10px] text-[var(--color-text-tertiary)] shrink-0">
+ {TYPE_LABELS[item.type]}
+ </span>
+ </div>
+ <p className="text-[11px] text-[var(--color-text-tertiary)] truncate">
+ {item.description}
+ </p>
+ </div>
+ </a>
+ );
+ })}
+ {items.length > 8 && (
+ <p className="text-[11px] text-[var(--color-text-tertiary)] text-center pt-1">
+ +{items.length - 8} more items
+ </p>
+ )}
+ </div>
+ </CardContent>
+ </Card>
+ );
+}
+
+function getDefaultHref(item: AttentionItem, repoId: string): string {
+ switch (item.type) {
+ case "stale_decision":
+ case "proposed_decision":
+ return `/repos/${repoId}/decisions`;
+ case "knowledge_silo":
+ return `/repos/${repoId}/ownership`;
+ case "ungoverned_hotspot":
+ return `/repos/${repoId}/hotspots`;
+ case "dead_code":
+ return `/repos/${repoId}/dead-code`;
+ default:
+ return `/repos/${repoId}`;
+ }
+}
+
diff --git a/packages/web/src/components/dashboard/decisions-timeline.tsx b/packages/web/src/components/dashboard/decisions-timeline.tsx
new file mode 100644
index 000000000..a1d4a7f81
--- /dev/null
+++ b/packages/web/src/components/dashboard/decisions-timeline.tsx
@@ -0,0 +1,102 @@
+import Link from "next/link";
+import { Landmark } from "lucide-react";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Badge } from "@/components/ui/badge";
+import type { DecisionRecordResponse } from "@/lib/api/types";
+import { formatRelativeTime } from "@/lib/utils/format";
+
+interface DecisionsTimelineProps {
+ decisions: DecisionRecordResponse[];
+ repoId: string;
+}
+
+const STATUS_COLORS: Record<string, string> = {
+ active: "bg-[var(--color-success)]",
+ proposed: "bg-[var(--color-info)]",
+ deprecated: "bg-[var(--color-error)]",
+ superseded: "bg-[var(--color-text-tertiary)]",
+};
+
+const STATUS_BADGE_VARIANT: Record<string, string> = {
+ active: "text-[var(--color-success)] border-[var(--color-success)]/30",
+ proposed: "text-[var(--color-info)] border-[var(--color-info)]/30",
+ deprecated: "text-[var(--color-error)] border-[var(--color-error)]/30",
+ superseded: "text-[var(--color-text-tertiary)] border-[var(--color-text-tertiary)]/30",
+};
+
+export function DecisionsTimeline({ decisions, repoId }: DecisionsTimelineProps) {
+ const recent = decisions.slice(0, 6);
+
+ if (recent.length === 0) {
+ return (
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm flex items-center gap-2">
+ <Landmark className="h-4 w-4 text-[var(--color-text-secondary)]" />
+ Recent Decisions
+ </CardTitle>
+ </CardHeader>
+ <CardContent className="pt-0">
+ <p className="text-xs text-[var(--color-text-tertiary)]">No decisions recorded</p>
+ </CardContent>
+ </Card>
+ );
+ }
+
+ return (
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm flex items-center justify-between">
+ <span className="flex items-center gap-2">
+ <Landmark className="h-4 w-4 text-[var(--color-text-secondary)]" />
+ Recent Decisions
+ </span>
+ <Link
+ href={`/repos/${repoId}/decisions`}
+ className="text-[10px] text-[var(--color-accent-primary)] hover:underline font-normal"
+ >
+ View all
+ </Link>
+ </CardTitle>
+ </CardHeader>
+ <CardContent className="pt-0">
+ <div className="relative">
+ {/* Timeline line */}
+ <div className="absolute left-[5px] top-1 bottom-1 w-px bg-[var(--color-border-default)]" />
+
+ <div className="space-y-3">
+ {recent.map((d) => (
+ <Link
+ key={d.id}
+ href={`/repos/${repoId}/decisions/${d.id}`}
+ className="flex items-start gap-3 pl-0 group relative"
+ >
+ {/* Dot */}
+ <span
+ className={`h-[11px] w-[11px] rounded-full shrink-0 mt-0.5 ring-2 ring-[var(--color-bg-surface)] relative z-10 ${STATUS_COLORS[d.status] ?? STATUS_COLORS.active}`}
+ />
+ <div className="min-w-0 flex-1">
+ <div className="flex items-center gap-2">
+ <span className="text-xs font-medium text-[var(--color-text-primary)] truncate group-hover:text-[var(--color-accent-primary)] transition-colors">
+ {d.title}
+ </span>
+ <Badge
+ variant="outline"
+ className={`text-[9px] h-4 shrink-0 ${STATUS_BADGE_VARIANT[d.status] ?? ""}`}
+ >
+ {d.status}
+ </Badge>
+ </div>
+ <span className="text-[10px] text-[var(--color-text-tertiary)]">
+ {formatRelativeTime(d.created_at)}
+ {d.source && ` · ${d.source.replace("_", " ")}`}
+ </span>
+ </div>
+ </Link>
+ ))}
+ </div>
+ </div>
+ </CardContent>
+ </Card>
+ );
+}
diff --git a/packages/web/src/components/dashboard/health-score-ring.tsx b/packages/web/src/components/dashboard/health-score-ring.tsx
new file mode 100644
index 000000000..b78530615
--- /dev/null
+++ b/packages/web/src/components/dashboard/health-score-ring.tsx
@@ -0,0 +1,80 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { motion } from "framer-motion";
+
+interface HealthScoreRingProps {
+ score: number; // 0-100
+ size?: number;
+}
+
+function getScoreColor(score: number): string {
+ if (score >= 75) return "var(--color-success)";
+ if (score >= 50) return "var(--color-warning)";
+ return "var(--color-error)";
+}
+
+function getScoreLabel(score: number): string {
+ if (score >= 80) return "Excellent";
+ if (score >= 65) return "Good";
+ if (score >= 50) return "Fair";
+ if (score >= 30) return "Needs Work";
+ return "Critical";
+}
+
+export function HealthScoreRing({ score, size = 160 }: HealthScoreRingProps) {
+ const [mounted, setMounted] = useState(false);
+ useEffect(() => setMounted(true), []);
+
+ const strokeWidth = 10;
+ const radius = (size - strokeWidth) / 2;
+ const circumference = 2 * Math.PI * radius;
+ const progress = mounted ? (score / 100) * circumference : 0;
+ const color = getScoreColor(score);
+
+ return (
+ <div className="relative flex items-center justify-center" style={{ width: size, height: size }}>
+ <svg width={size} height={size} className="-rotate-90">
+ {/* Background track */}
+ <circle
+ cx={size / 2}
+ cy={size / 2}
+ r={radius}
+ fill="none"
+ stroke="var(--color-border-default)"
+ strokeWidth={strokeWidth}
+ />
+ {/* Animated progress arc */}
+ <motion.circle
+ cx={size / 2}
+ cy={size / 2}
+ r={radius}
+ fill="none"
+ stroke={color}
+ strokeWidth={strokeWidth}
+ strokeLinecap="round"
+ strokeDasharray={circumference}
+ initial={{ strokeDashoffset: circumference }}
+ animate={{ strokeDashoffset: circumference - progress }}
+ transition={{ duration: 1.2, ease: "easeOut" }}
+ />
+ </svg>
+ {/* Center text */}
+ <div className="absolute inset-0 flex flex-col items-center justify-center">
+ <motion.span
+ className="text-3xl font-bold tabular-nums"
+ style={{ color }}
+ initial={{ opacity: 0 }}
+ animate={{ opacity: 1 }}
+ transition={{ delay: 0.3 }}
+ >
+ {score}
+ </motion.span>
+ <span className="text-[10px] uppercase tracking-wider text-[var(--color-text-tertiary)]">
+ {getScoreLabel(score)}
+ </span>
+ </div>
+ </div>
+ );
+}
+
diff --git a/packages/web/src/components/dashboard/hotspots-mini.tsx b/packages/web/src/components/dashboard/hotspots-mini.tsx
new file mode 100644
index 000000000..e41b4d26c
--- /dev/null
+++ b/packages/web/src/components/dashboard/hotspots-mini.tsx
@@ -0,0 +1,88 @@
+import Link from "next/link";
+import { Flame } from "lucide-react";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import type { HotspotResponse } from "@/lib/api/types";
+import { truncatePath } from "@/lib/utils/format";
+
+interface HotspotsMiniProps {
+ hotspots: HotspotResponse[];
+ repoId: string;
+}
+
+export function HotspotsMini({ hotspots, repoId }: HotspotsMiniProps) {
+ const top = hotspots.slice(0, 5);
+
+ if (top.length === 0) {
+ return (
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm flex items-center gap-2">
+ <Flame className="h-4 w-4 text-red-500" />
+ Top Hotspots
+ </CardTitle>
+ </CardHeader>
+ <CardContent className="pt-0">
+ <p className="text-xs text-[var(--color-text-tertiary)]">No hotspot data</p>
+ </CardContent>
+ </Card>
+ );
+ }
+
+ return (
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm flex items-center justify-between">
+ <span className="flex items-center gap-2">
+ <Flame className="h-4 w-4 text-red-500" />
+ Top Hotspots
+ </span>
+ <Link
+ href={`/repos/${repoId}/hotspots`}
+ className="text-[10px] text-[var(--color-accent-primary)] hover:underline font-normal"
+ >
+ View all
+ </Link>
+ </CardTitle>
+ </CardHeader>
+ <CardContent className="pt-0">
+ <div className="space-y-2">
+ {top.map((h) => (
+ <div key={h.file_path} className="flex items-center gap-3">
+ {/* Churn bar */}
+ <div className="w-16 shrink-0">
+ <div className="h-1.5 rounded-full bg-[var(--color-bg-elevated)] overflow-hidden">
+ <div
+ className="h-full rounded-full transition-all"
+ style={{
+ width: `${h.churn_percentile}%`,
+ backgroundColor: getChurnColor(h.churn_percentile),
+ }}
+ />
+ </div>
+ </div>
+ {/* File info */}
+ <div className="min-w-0 flex-1">
+ <p className="text-[11px] font-mono text-[var(--color-text-primary)] truncate">
+ {truncatePath(h.file_path, 40)}
+ </p>
+ </div>
+ {/* Stats */}
+ <div className="flex items-center gap-2 shrink-0 text-[10px] text-[var(--color-text-tertiary)] tabular-nums">
+ <span>{h.commit_count_90d}c/90d</span>
+ <span className="text-[var(--color-text-secondary)]">
+ {Math.round(h.churn_percentile)}%
+ </span>
+ </div>
+ </div>
+ ))}
+ </div>
+ </CardContent>
+ </Card>
+ );
+}
+
+function getChurnColor(percentile: number): string {
+ if (percentile >= 95) return "var(--color-error)";
+ if (percentile >= 80) return "var(--color-warning)";
+ return "var(--color-accent-primary)";
+}
diff --git a/packages/web/src/components/dashboard/language-donut.tsx b/packages/web/src/components/dashboard/language-donut.tsx
new file mode 100644
index 000000000..b77cddc17
--- /dev/null
+++ b/packages/web/src/components/dashboard/language-donut.tsx
@@ -0,0 +1,104 @@
+"use client";
+
+import { PieChart, Pie, Cell, ResponsiveContainer, Tooltip } from "recharts";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Code } from "lucide-react";
+
+const LANG_COLORS: Record<string, string> = {
+ python: "var(--color-lang-python)",
+ typescript: "var(--color-lang-typescript)",
+ javascript: "var(--color-lang-typescript)",
+ go: "var(--color-lang-go)",
+ rust: "var(--color-lang-rust)",
+ java: "var(--color-lang-java)",
+ cpp: "var(--color-lang-cpp)",
+ c: "var(--color-lang-cpp)",
+ config: "var(--color-lang-config)",
+};
+
+function getLangColor(lang: string): string {
+ return LANG_COLORS[lang.toLowerCase()] ?? "var(--color-lang-other)";
+}
+
+interface LanguageDonutProps {
+ /** Map of language → file count */
+ distribution: Record<string, number>;
+}
+
+export function LanguageDonut({ distribution }: LanguageDonutProps) {
+ const entries = Object.entries(distribution)
+ .map(([name, value]) => ({ name, value }))
+ .sort((a, b) => b.value - a.value);
+
+ const total = entries.reduce((s, e) => s + e.value, 0);
+ if (total === 0) return null;
+
+ // Show top 6, group rest as "other"
+ const shown = entries.slice(0, 6);
+ const otherValue = entries.slice(6).reduce((s, e) => s + e.value, 0);
+ if (otherValue > 0) shown.push({ name: "other", value: otherValue });
+
+ return (
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm flex items-center gap-2">
+ <Code className="h-4 w-4 text-[var(--color-text-secondary)]" />
+ Languages
+ </CardTitle>
+ </CardHeader>
+ <CardContent className="pt-0">
+ <div className="flex items-center gap-4">
+ <div className="w-[120px] h-[120px] shrink-0">
+ <ResponsiveContainer width="100%" height="100%">
+ <PieChart>
+ <Pie
+ data={shown}
+ cx="50%"
+ cy="50%"
+ innerRadius={32}
+ outerRadius={55}
+ paddingAngle={2}
+ dataKey="value"
+ stroke="none"
+ >
+ {shown.map((entry) => (
+ <Cell key={entry.name} fill={getLangColor(entry.name)} />
+ ))}
+ </Pie>
+ <Tooltip
+ contentStyle={{
+ background: "var(--color-bg-overlay)",
+ border: "1px solid var(--color-border-default)",
+ borderRadius: 8,
+ fontSize: 11,
+ color: "var(--color-text-primary)",
+ }}
+ formatter={(value: number) => [`${value} files (${Math.round((value / total) * 100)}%)`, ""]}
+ />
+ </PieChart>
+ </ResponsiveContainer>
+ </div>
+ <div className="space-y-1.5 min-w-0 flex-1">
+ {shown.map((entry) => (
+ <div key={entry.name} className="flex items-center justify-between text-[11px]">
+ <div className="flex items-center gap-1.5 min-w-0">
+ <span
+ className="h-2 w-2 rounded-full shrink-0"
+ style={{ backgroundColor: getLangColor(entry.name) }}
+ />
+ <span className="text-[var(--color-text-secondary)] capitalize truncate">
+ {entry.name}
+ </span>
+ </div>
+ <span className="text-[var(--color-text-tertiary)] tabular-nums ml-2 shrink-0">
+ {Math.round((entry.value / total) * 100)}%
+ </span>
+ </div>
+ ))}
+ </div>
+ </div>
+ </CardContent>
+ </Card>
+ );
+}
+
diff --git a/packages/web/src/components/dashboard/module-minimap.tsx b/packages/web/src/components/dashboard/module-minimap.tsx
new file mode 100644
index 000000000..73996026b
--- /dev/null
+++ b/packages/web/src/components/dashboard/module-minimap.tsx
@@ -0,0 +1,192 @@
+"use client";
+
+import { useRef, useEffect, useState, useCallback } from "react";
+import * as d3Force from "d3-force";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
+import { Network } from "lucide-react";
+import Link from "next/link";
+import type { ModuleNodeResponse, ModuleEdgeResponse } from "@/lib/api/types";
+
+interface ModuleMinimapProps {
+ nodes: ModuleNodeResponse[];
+ edges: ModuleEdgeResponse[];
+ repoId: string;
+}
+
+interface SimNode extends d3Force.SimulationNodeDatum {
+ id: string;
+ fileCount: number;
+ symbolCount: number;
+ docCoverage: number;
+ label: string;
+}
+
+interface SimLink {
+ source: string;
+ target: string;
+ edgeCount: number;
+}
+
+export function ModuleMinimap({ nodes, edges, repoId }: ModuleMinimapProps) {
+ const containerRef = useRef<HTMLDivElement>(null);
+ const [simNodes, setSimNodes] = useState<SimNode[]>([]);
+ const [simLinks, setSimLinks] = useState<Array<{ source: SimNode; target: SimNode; edgeCount: number }>>([]);
+ const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
+ const [hoveredNode, setHoveredNode] = useState<string | null>(null);
+
+ useEffect(() => {
+ if (!containerRef.current) return;
+ const observer = new ResizeObserver((es) => {
+ const { width, height } = es[0].contentRect;
+ setDimensions({ width, height: Math.max(height, 200) });
+ });
+ observer.observe(containerRef.current);
+ return () => observer.disconnect();
+ }, []);
+
+ useEffect(() => {
+ if (nodes.length === 0 || dimensions.width === 0) return;
+
+ const sNodes: SimNode[] = nodes.map((n) => ({
+ id: n.module_id,
+ fileCount: n.file_count,
+ symbolCount: n.symbol_count,
+ docCoverage: n.doc_coverage_pct,
+ label: n.module_id.split("/").pop() ?? n.module_id,
+ }));
+
+ const nodeIds = new Set(sNodes.map((n) => n.id));
+ const sLinks: SimLink[] = edges
+ .filter((e) => nodeIds.has(e.source) && nodeIds.has(e.target))
+ .map((e) => ({ source: e.source, target: e.target, edgeCount: e.edge_count }));
+
+ const sim = d3Force
+ .forceSimulation(sNodes)
+ .force(
+ "link",
+ d3Force.forceLink<SimNode, SimLink>(sLinks as never[]).id((d: SimNode) => d.id).distance(60)
+ )
+ .force("charge", d3Force.forceManyBody().strength(-120))
+ .force("center", d3Force.forceCenter(dimensions.width / 2, dimensions.height / 2))
+ .force("collision", d3Force.forceCollide().radius(20))
+ .alpha(0.8)
+ .alphaDecay(0.05);
+
+ sim.on("end", () => {
+ setSimNodes([...sNodes]);
+ setSimLinks(
+ sLinks.map((l) => ({
+ source: sNodes.find((n) => n.id === (typeof l.source === "string" ? l.source : (l.source as SimNode).id))!,
+ target: sNodes.find((n) => n.id === (typeof l.target === "string" ? l.target : (l.target as SimNode).id))!,
+ edgeCount: l.edgeCount,
+ }))
+ );
+ });
+
+ // Run simulation synchronously for small graphs
+ sim.tick(150);
+ sim.stop();
+ setSimNodes([...sNodes]);
+ setSimLinks(
+ sLinks.map((l) => ({
+ source: sNodes.find((n) => n.id === (typeof l.source === "string" ? l.source : (l.source as SimNode).id))!,
+ target: sNodes.find((n) => n.id === (typeof l.target === "string" ? l.target : (l.target as SimNode).id))!,
+ edgeCount: l.edgeCount,
+ }))
+ );
+
+ return () => { sim.stop(); };
+ }, [nodes, edges, dimensions]);
+
+ const getNodeRadius = useCallback(
+ (n: SimNode) => Math.max(4, Math.min(16, Math.sqrt(n.fileCount) * 3)),
+ []
+ );
+
+ if (nodes.length === 0) return null;
+
+ const { width, height } = dimensions;
+
+ return (
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm flex items-center justify-between">
+ <span className="flex items-center gap-2">
+ <Network className="h-4 w-4 text-[var(--color-text-secondary)]" />
+ Architecture
+ </span>
+ <Link
+ href={`/repos/${repoId}/graph`}
+ className="text-[10px] text-[var(--color-accent-primary)] hover:underline font-normal"
+ >
+ Full graph
+ </Link>
+ </CardTitle>
+ </CardHeader>
+ <CardContent className="pt-0">
+ <div ref={containerRef} className="h-[220px] relative">
+ {width > 0 && simNodes.length > 0 && (
+ <TooltipProvider delayDuration={100}>
+ <svg width={width} height={height}>
+ {/* Edges */}
+ {simLinks.map((link, i) => (
+ <line
+ key={i}
+ x1={link.source.x ?? 0}
+ y1={link.source.y ?? 0}
+ x2={link.target.x ?? 0}
+ y2={link.target.y ?? 0}
+ stroke="var(--color-border-default)"
+ strokeWidth={Math.min(link.edgeCount * 0.5, 3)}
+ opacity={
+ hoveredNode
+ ? hoveredNode === link.source.id || hoveredNode === link.target.id
+ ? 0.8
+ : 0.1
+ : 0.4
+ }
+ className="transition-opacity"
+ />
+ ))}
+ {/* Nodes */}
+ {simNodes.map((node) => {
+ const r = getNodeRadius(node);
+ const isHovered = hoveredNode === node.id;
+ const docColor =
+ node.docCoverage >= 70
+ ? "var(--color-node-documented)"
+ : node.docCoverage >= 30
+ ? "var(--color-warning)"
+ : "var(--color-node-undocumented)";
+ return (
+ <Tooltip key={node.id}>
+ <TooltipTrigger asChild>
+ <circle
+ cx={node.x ?? 0}
+ cy={node.y ?? 0}
+ r={isHovered ? r + 2 : r}
+ fill={docColor}
+ opacity={hoveredNode && !isHovered ? 0.3 : 0.8}
+ className="transition-all cursor-pointer"
+ onMouseEnter={() => setHoveredNode(node.id)}
+ onMouseLeave={() => setHoveredNode(null)}
+ />
+ </TooltipTrigger>
+ <TooltipContent side="top" className="text-xs">
+ <p className="font-medium font-mono">{node.id}</p>
+ <p className="text-[var(--color-text-tertiary)]">
+ {node.fileCount} files · {node.symbolCount} symbols · {Math.round(node.docCoverage)}% docs
+ </p>
+ </TooltipContent>
+ </Tooltip>
+ );
+ })}
+ </svg>
+ </TooltipProvider>
+ )}
+ </div>
+ </CardContent>
+ </Card>
+ );
+}
diff --git a/packages/web/src/components/dashboard/ownership-treemap.tsx b/packages/web/src/components/dashboard/ownership-treemap.tsx
new file mode 100644
index 000000000..f134bf4e5
--- /dev/null
+++ b/packages/web/src/components/dashboard/ownership-treemap.tsx
@@ -0,0 +1,170 @@
+"use client";
+
+import { useRef, useEffect, useState } from "react";
+import * as d3 from "d3-hierarchy";
+import type { OwnershipEntry } from "@/lib/api/types";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
+import { Users } from "lucide-react";
+
+// Owner color palette — muted, high contrast on dark
+const OWNER_COLORS = [
+ "#3b82f6", "#8b5cf6", "#06b6d4", "#f59520", "#22c55e",
+ "#ec4899", "#eab308", "#ef4444", "#14b8a6", "#a855f7",
+ "#6366f1", "#f97316",
+];
+
+interface OwnershipTreemapProps {
+ entries: OwnershipEntry[];
+}
+
+interface TreemapNode {
+ name: string;
+ value: number;
+ owner: string | null;
+ ownerPct: number | null;
+ isSilo: boolean;
+}
+
+export function OwnershipTreemap({ entries }: OwnershipTreemapProps) {
+ const containerRef = useRef<HTMLDivElement>(null);
+ const [dimensions, setDimensions] = useState({ width: 0, height: 0 });
+ const [hoveredNode, setHoveredNode] = useState<TreemapNode | null>(null);
+
+ useEffect(() => {
+ if (!containerRef.current) return;
+ const observer = new ResizeObserver((es) => {
+ const { width, height } = es[0].contentRect;
+ setDimensions({ width, height: Math.max(height, 200) });
+ });
+ observer.observe(containerRef.current);
+ return () => observer.disconnect();
+ }, []);
+
+ if (entries.length === 0) return null;
+
+ // Build unique owner → color map
+ const owners = [...new Set(entries.map((e) => e.primary_owner).filter(Boolean))] as string[];
+ const ownerColorMap = new Map<string, string>();
+ owners.forEach((o, i) => ownerColorMap.set(o, OWNER_COLORS[i % OWNER_COLORS.length]));
+
+ // Build hierarchy
+ const root = d3
+ .hierarchy<{ children: TreemapNode[] } | TreemapNode>({
+ children: entries.map((e) => ({
+ name: e.module_path,
+ value: Math.max(e.file_count, 1),
+ owner: e.primary_owner,
+ ownerPct: e.owner_pct,
+ isSilo: e.is_silo,
+ })),
+ } as { children: TreemapNode[] })
+ .sum((d) => ("value" in d ? (d as TreemapNode).value : 0));
+
+ const { width, height } = dimensions;
+
+ if (width === 0) {
+ return (
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm flex items-center gap-2">
+ <Users className="h-4 w-4 text-[var(--color-text-secondary)]" />
+ Ownership Map
+ </CardTitle>
+ </CardHeader>
+ <CardContent className="pt-0">
+ <div ref={containerRef} className="h-[220px]" />
+ </CardContent>
+ </Card>
+ );
+ }
+
+ const treemap = d3.treemap<{ children: TreemapNode[] } | TreemapNode>()
+ .size([width, height])
+ .padding(2)
+ .round(true);
+
+ treemap(root);
+
+ const leaves = root.leaves() as Array<d3.HierarchyRectangularNode<TreemapNode>>;
+
+ return (
+ <Card>
+ <CardHeader className="pb-2">
+ <CardTitle className="text-sm flex items-center gap-2">
+ <Users className="h-4 w-4 text-[var(--color-text-secondary)]" />
+ Ownership Map
+ </CardTitle>
+ </CardHeader>
+ <CardContent className="pt-0">
+ <div ref={containerRef} className="h-[220px] relative">
+ <TooltipProvider delayDuration={100}>
+ <svg width={width} height={height}>
+ {leaves.map((leaf) => {
+ const d = leaf.data as TreemapNode;
+ const color = d.owner ? (ownerColorMap.get(d.owner) ?? "var(--color-text-tertiary)") : "var(--color-text-tertiary)";
+ const opacity = d.isSilo ? 0.45 : 0.75;
+ const w = (leaf.x1 ?? 0) - (leaf.x0 ?? 0);
+ const h = (leaf.y1 ?? 0) - (leaf.y0 ?? 0);
+ return (
+ <Tooltip key={d.name}>
+ <TooltipTrigger asChild>
+ <rect
+ x={leaf.x0}
+ y={leaf.y0}
+ width={w}
+ height={h}
+ rx={3}
+ fill={color}
+ opacity={hoveredNode?.name === d.name ? 1 : opacity}
+ className="transition-opacity cursor-pointer"
+ onMouseEnter={() => setHoveredNode(d)}
+ onMouseLeave={() => setHoveredNode(null)}
+ />
+ </TooltipTrigger>
+ {w > 40 && h > 16 && (
+ <text
+ x={(leaf.x0 ?? 0) + 4}
+ y={(leaf.y0 ?? 0) + 14}
+ className="text-[10px] fill-white pointer-events-none"
+ opacity={0.9}
+ >
+ {d.name.length > w / 6 ? d.name.slice(0, Math.floor(w / 6)) + "…" : d.name}
+ </text>
+ )}
+ <TooltipContent side="top" className="text-xs">
+ <p className="font-medium">{d.name}</p>
+ <p className="text-[var(--color-text-tertiary)]">
+ Owner: {d.owner ?? "none"} ({d.ownerPct ? Math.round(d.ownerPct * 100) : 0}%)
+ </p>
+ <p className="text-[var(--color-text-tertiary)]">
+ {d.value} files{d.isSilo ? " • Knowledge silo" : ""}
+ </p>
+ </TooltipContent>
+ </Tooltip>
+ );
+ })}
+ </svg>
+ </TooltipProvider>
+ </div>
+ {/* Legend */}
+ <div className="flex flex-wrap gap-x-3 gap-y-1 mt-2">
+ {owners.slice(0, 6).map((owner) => (
+ <div key={owner} className="flex items-center gap-1.5 text-[10px] text-[var(--color-text-secondary)]">
+ <span
+ className="h-2 w-2 rounded-full shrink-0"
+ style={{ backgroundColor: ownerColorMap.get(owner) }}
+ />
+ {owner}
+ </div>
+ ))}
+ {owners.length > 6 && (
+ <span className="text-[10px] text-[var(--color-text-tertiary)]">
+ +{owners.length - 6} more
+ </span>
+ )}
+ </div>
+ </CardContent>
+ </Card>
+ );
+}
diff --git a/packages/web/src/components/dashboard/quick-actions.tsx b/packages/web/src/components/dashboard/quick-actions.tsx
new file mode 100644
index 000000000..b9ba8de99
--- /dev/null
+++ b/packages/web/src/components/dashboard/quick-actions.tsx
@@ -0,0 +1,303 @@
+"use client";
+
+import { useState } from "react";
+import { toast } from "sonner";
+import { RefreshCw, FileText, Trash2, AlertTriangle, Zap } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import {
+ Dialog,
+ DialogContent,
+ DialogHeader,
+ DialogTitle,
+ DialogDescription,
+ DialogFooter,
+} from "@/components/ui/dialog";
+import { syncRepo, fullResyncRepo } from "@/lib/api/repos";
+import { analyzeDeadCode } from "@/lib/api/dead-code";
+import { GenerationProgress } from "@/components/jobs/generation-progress";
+import { formatNumber, formatCost, formatRelativeTime } from "@/lib/utils/format";
+
+// Weighted average per-page token heuristics from cost_estimator.py _TOKEN_HEURISTICS
+const AVG_INPUT_TOKENS_PER_PAGE = 3500;
+const AVG_OUTPUT_TOKENS_PER_PAGE = 2200;
+
+// Pricing per 1K tokens (input, output) — mirrors cost_estimator.py _COST_TABLE exactly
+const COST_TABLE_EXACT: Record<string, [number, number]> = {
+ "gpt-5.4": [0.0025, 0.015],
+ "gpt-5.4-mini": [0.00075, 0.0045],
+ "gpt-5.4-nano": [0.0002, 0.00125],
+ "gemini-3.1-pro-preview": [0.002, 0.012],
+ "gemini-3-flash-preview": [0.0005, 0.003],
+ "gemini-3.1-flash-lite-preview": [0.00025, 0.0015],
+ "claude-opus-4-6": [0.005, 0.025],
+ "claude-sonnet-4-6": [0.003, 0.015],
+ "claude-haiku-4-5": [0.001, 0.005],
+};
+
+// Prefix fallbacks — longest match wins (same as cost_estimator.py)
+const COST_TABLE_PREFIX: [string, [number, number]][] = [
+ ["gpt-5.4-nano", [0.0002, 0.00125]],
+ ["gpt-5.4-mini", [0.00075, 0.0045]],
+ ["gpt-5.4", [0.0025, 0.015]],
+ ["claude-opus", [0.005, 0.025]],
+ ["claude-sonnet", [0.003, 0.015]],
+ ["claude-haiku", [0.001, 0.005]],
+ ["claude", [0.003, 0.015]],
+ ["gemini", [0.00025, 0.0015]],
+ ["llama", [0, 0]],
+ ["mock", [0, 0]],
+];
+
+function lookupCost(modelName: string): [number, number] {
+ const lower = modelName.toLowerCase();
+ if (lower in COST_TABLE_EXACT) return COST_TABLE_EXACT[lower];
+ let bestLen = 0;
+ let bestRates: [number, number] = [0, 0];
+ for (const [prefix, rates] of COST_TABLE_PREFIX) {
+ if (lower.startsWith(prefix) && prefix.length > bestLen) {
+ bestLen = prefix.length;
+ bestRates = rates;
+ }
+ }
+ return bestRates;
+}
+
+function estimateCost(pageCount: number, modelName: string): { inputTokens: number; outputTokens: number; cost: number } {
+ const inputTokens = pageCount * AVG_INPUT_TOKENS_PER_PAGE;
+ const outputTokens = pageCount * AVG_OUTPUT_TOKENS_PER_PAGE;
+ const [inputRate, outputRate] = lookupCost(modelName);
+ // cost_estimator.py: (total_input / 1000) * input_rate + (total_output / 1000) * output_rate
+ const cost = (inputTokens / 1000) * inputRate + (outputTokens / 1000) * outputRate;
+ return { inputTokens, outputTokens, cost };
+}
+
+type ActionKey = "sync" | "resync" | "dead-code";
+
+interface ActionDef {
+ key: ActionKey;
+ label: string;
+ description: string;
+ icon: typeof RefreshCw;
+ destructive: boolean;
+ needsConfirm: boolean;
+ confirmTitle: string;
+ confirmDescription: string;
+}
+
+const ACTIONS: ActionDef[] = [
+ {
+ key: "sync",
+ label: "Sync",
+ description: "Incremental re-index — only changed files",
+ icon: Zap,
+ destructive: false,
+ needsConfirm: true,
+ confirmTitle: "Sync Repository",
+ confirmDescription: "This will re-index changed files and regenerate affected pages.",
+ },
+ {
+ key: "resync",
+ label: "Full Re-index",
+ description: "Regenerate all docs from scratch",
+ icon: RefreshCw,
+ destructive: true,
+ needsConfirm: true,
+ confirmTitle: "Full Re-index",
+ confirmDescription: "This regenerates every page from scratch. All existing pages will be overwritten.",
+ },
+ {
+ key: "dead-code",
+ label: "Dead Code Scan",
+ description: "Analyze for unused exports and files",
+ icon: Trash2,
+ destructive: false,
+ needsConfirm: false,
+ confirmTitle: "",
+ confirmDescription: "",
+ },
+];
+
+interface QuickActionsProps {
+ repoId: string;
+ repoName?: string;
+ pageCount?: number;
+ modelName?: string;
+ lastSyncAt?: string | null;
+ lastResyncAt?: string | null;
+}
+
+export function QuickActions({ repoId, repoName, pageCount = 0, modelName = "", lastSyncAt, lastResyncAt }: QuickActionsProps) {
+ const [loading, setLoading] = useState<ActionKey | null>(null);
+ const [pendingAction, setPendingAction] = useState<ActionDef | null>(null);
+ const [activeJobId, setActiveJobId] = useState<string | null>(null);
+
+ const estimate = pageCount > 0 && pendingAction?.key !== "dead-code"
+ ? estimateCost(
+ pendingAction?.key === "sync" ? Math.ceil(pageCount * 0.15) : pageCount,
+ modelName
+ )
+ : null;
+
+ async function executeAction(action: ActionDef) {
+ setLoading(action.key);
+ setPendingAction(null);
+ try {
+ if (action.key === "sync") {
+ const job = await syncRepo(repoId);
+ setActiveJobId(job.id);
+ toast.info(`Sync started${repoName ? ` — ${repoName}` : ""}`);
+ } else if (action.key === "resync") {
+ const job = await fullResyncRepo(repoId);
+ setActiveJobId(job.id);
+ toast.info(`Full resync started${repoName ? ` — ${repoName}` : ""}`);
+ } else if (action.key === "dead-code") {
+ await analyzeDeadCode(repoId);
+ toast.info("Dead code analysis started");
+ }
+ } catch (e) {
+ toast.error(`${action.label} failed`, {
+ description: e instanceof Error ? e.message : "Unknown error",
+ });
+ } finally {
+ setLoading(null);
+ }
+ }
+
+ function handleClick(action: ActionDef) {
+ if (action.needsConfirm) {
+ setPendingAction(action);
+ } else {
+ executeAction(action);
+ }
+ }
+
+ return (
+ <>
+ {/* Active job progress */}
+ {activeJobId && (
+ <div className="mb-2">
+ <GenerationProgress
+ jobId={activeJobId}
+ repoName={repoName}
+ onDone={() => setActiveJobId(null)}
+ />
+ </div>
+ )}
+
+ {/* Action buttons + timestamps */}
+ {!activeJobId && (
+ <div className="space-y-1.5">
+ <div className="flex flex-wrap gap-2">
+ {ACTIONS.map((action) => {
+ const Icon = action.icon;
+ const isLoading = loading === action.key;
+ return (
+ <Button
+ key={action.key}
+ variant="outline"
+ size="sm"
+ className="h-8 gap-1.5 text-xs"
+ disabled={loading !== null}
+ onClick={() => handleClick(action)}
+ >
+ <Icon className={`h-3.5 w-3.5 ${isLoading ? "animate-spin" : ""}`} />
+ {action.label}
+ </Button>
+ );
+ })}
+ </div>
+ <div className="flex flex-wrap gap-x-4 gap-y-0.5">
+ <span className="text-[11px] text-[var(--color-text-tertiary)]">
+ Last synced{" "}
+ <span className="text-[var(--color-text-secondary)]">
+ {lastSyncAt ? formatRelativeTime(lastSyncAt) : "never"}
+ </span>
+ </span>
+ <span className="text-[11px] text-[var(--color-text-tertiary)]">
+ Last re-indexed{" "}
+ <span className="text-[var(--color-text-secondary)]">
+ {lastResyncAt ? formatRelativeTime(lastResyncAt) : "never"}
+ </span>
+ </span>
+ </div>
+ </div>
+ )}
+
+ {/* Confirmation dialog */}
+ <Dialog open={pendingAction !== null} onOpenChange={(open) => !open && setPendingAction(null)}>
+ {pendingAction && (
+ <DialogContent className="sm:max-w-sm">
+ <DialogHeader>
+ <DialogTitle className="flex items-center gap-2">
+ {pendingAction.destructive && (
+ <AlertTriangle className="h-4 w-4 text-[var(--color-warning)]" />
+ )}
+ {pendingAction.confirmTitle}
+ </DialogTitle>
+ <DialogDescription>
+ {pendingAction.confirmDescription}
+ </DialogDescription>
+ </DialogHeader>
+
+ {/* Cost estimate */}
+ {estimate && estimate.cost > 0 && (
+ <div className="rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-inset)] p-3 space-y-2">
+ <p className="text-xs font-medium text-[var(--color-text-secondary)] uppercase tracking-wider">
+ Estimated Cost
+ </p>
+ <div className="grid grid-cols-3 gap-2 text-center">
+ <div>
+ <p className="text-sm font-semibold text-[var(--color-text-primary)] tabular-nums">
+ {formatNumber(pendingAction.key === "sync" ? Math.ceil(pageCount * 0.15) : pageCount)}
+ </p>
+ <p className="text-[10px] text-[var(--color-text-tertiary)]">pages</p>
+ </div>
+ <div>
+ <p className="text-sm font-semibold text-[var(--color-text-primary)] tabular-nums">
+ {formatNumber(estimate.inputTokens + estimate.outputTokens)}
+ </p>
+ <p className="text-[10px] text-[var(--color-text-tertiary)]">tokens</p>
+ </div>
+ <div>
+ <p className="text-sm font-semibold text-[var(--color-accent-primary)] tabular-nums">
+ ~{formatCost(estimate.cost)}
+ </p>
+ <p className="text-[10px] text-[var(--color-text-tertiary)]">
+ {modelName || "est."}
+ </p>
+ </div>
+ </div>
+ {estimate.cost < 0.01 && (
+ <p className="text-[10px] text-[var(--color-text-tertiary)] text-center">
+ Free or near-free with this model
+ </p>
+ )}
+ </div>
+ )}
+
+ {estimate && estimate.cost === 0 && (
+ <div className="rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-inset)] p-3">
+ <p className="text-xs text-[var(--color-success)] text-center">
+ No API cost — running locally via Ollama
+ </p>
+ </div>
+ )}
+
+ <DialogFooter>
+ <Button variant="ghost" size="sm" onClick={() => setPendingAction(null)}>
+ Cancel
+ </Button>
+ <Button
+ variant={pendingAction.destructive ? "destructive" : "default"}
+ size="sm"
+ onClick={() => executeAction(pendingAction)}
+ >
+ {pendingAction.label}
+ </Button>
+ </DialogFooter>
+ </DialogContent>
+ )}
+ </Dialog>
+ </>
+ );
+}
diff --git a/packages/web/src/components/layout/mobile-nav.tsx b/packages/web/src/components/layout/mobile-nav.tsx
index a60a0fbdb..a4136066f 100644
--- a/packages/web/src/components/layout/mobile-nav.tsx
+++ b/packages/web/src/components/layout/mobile-nav.tsx
@@ -6,8 +6,11 @@ import { usePathname } from "next/navigation";
import Image from "next/image";
import {
Menu,
+ Activity,
BookOpen,
LayoutDashboard,
+ Lightbulb,
+ MessageSquare,
Settings,
Search,
GitBranch,
@@ -36,7 +39,9 @@ const GLOBAL_NAV = [
function repoNavItems(repoId: string) {
return [
- { label: "Overview", href: `/repos/${repoId}`, icon: BookOpen },
+ { label: "Overview", href: `/repos/${repoId}/overview`, icon: Activity },
+ { label: "Chat", href: `/repos/${repoId}`, icon: MessageSquare },
+ { label: "Docs", href: `/repos/${repoId}/docs`, icon: BookOpen },
{ label: "Search", href: `/repos/${repoId}/search`, icon: Search },
{ label: "Graph", href: `/repos/${repoId}/graph`, icon: GitBranch },
{ label: "Symbols", href: `/repos/${repoId}/symbols`, icon: Code2 },
@@ -44,6 +49,7 @@ function repoNavItems(repoId: string) {
{ label: "Ownership", href: `/repos/${repoId}/ownership`, icon: Users },
{ label: "Hotspots", href: `/repos/${repoId}/hotspots`, icon: Flame },
{ label: "Dead Code", href: `/repos/${repoId}/dead-code`, icon: Trash2 },
+ { label: "Decisions", href: `/repos/${repoId}/decisions`, icon: Lightbulb },
{ label: "Settings", href: `/repos/${repoId}/settings`, icon: SlidersHorizontal },
];
}
diff --git a/packages/web/src/components/layout/sidebar.tsx b/packages/web/src/components/layout/sidebar.tsx
index d42c391f0..dd40b9b61 100644
--- a/packages/web/src/components/layout/sidebar.tsx
+++ b/packages/web/src/components/layout/sidebar.tsx
@@ -6,6 +6,7 @@ import { usePathname } from "next/navigation";
import Image from "next/image";
import {
LayoutDashboard,
+ Activity,
BookOpen,
GitBranch,
Lightbulb,
@@ -43,6 +44,7 @@ const GLOBAL_NAV: NavItem[] = [
function repoNavItems(repoId: string): NavItem[] {
return [
+ { label: "Overview", href: `/repos/${repoId}/overview`, icon: Activity },
{ label: "Chat", href: `/repos/${repoId}`, icon: MessageSquare },
{ label: "Docs", href: `/repos/${repoId}/docs`, icon: BookOpen },
{ label: "Search", href: `/repos/${repoId}/search`, icon: Search },
diff --git a/packages/web/src/lib/utils/health-score.ts b/packages/web/src/lib/utils/health-score.ts
new file mode 100644
index 000000000..e81b93aa8
--- /dev/null
+++ b/packages/web/src/lib/utils/health-score.ts
@@ -0,0 +1,141 @@
+/** Compute composite health score from available repo data */
+export function computeHealthScore(params: {
+ docCoveragePct: number;
+ freshnessScore: number;
+ deadExportCount: number;
+ symbolCount: number;
+ hotspotCount: number;
+ totalFiles: number;
+ siloCount: number;
+ totalModules: number;
+}): number {
+ const {
+ docCoveragePct,
+ freshnessScore,
+ deadExportCount,
+ symbolCount,
+ hotspotCount,
+ totalFiles,
+ siloCount,
+ totalModules,
+ } = params;
+
+ // Doc coverage: 0-100, weight 25%
+ const docScore = Math.min(docCoveragePct, 100);
+
+ // Freshness: 0-100, weight 25%
+ const freshScore = Math.min(freshnessScore * 100, 100);
+
+ // Dead code: lower is better, weight 20%
+ const deadRatio = symbolCount > 0 ? deadExportCount / symbolCount : 0;
+ const deadScore = Math.max(0, (1 - deadRatio * 5) * 100); // 20% dead = 0 score
+
+ // Hotspot density: lower is better, weight 15%
+ const hotspotRatio = totalFiles > 0 ? hotspotCount / totalFiles : 0;
+ const hotspotScore = Math.max(0, (1 - hotspotRatio * 3) * 100);
+
+ // Knowledge distribution: fewer silos is better, weight 15%
+ const siloRatio = totalModules > 0 ? siloCount / totalModules : 0;
+ const siloScore = Math.max(0, (1 - siloRatio * 2) * 100);
+
+ const composite = Math.round(
+ docScore * 0.25 +
+ freshScore * 0.25 +
+ deadScore * 0.2 +
+ hotspotScore * 0.15 +
+ siloScore * 0.15
+ );
+
+ return Math.max(0, Math.min(100, composite));
+}
+
+/** Aggregate language distribution from graph nodes */
+export function aggregateLanguages(
+ nodes: Array<{ language: string; node_type: string }>
+): Record<string, number> {
+ const counts: Record<string, number> = {};
+ for (const n of nodes) {
+ if (n.node_type === "file" || !n.node_type) {
+ const lang = n.language?.toLowerCase() || "unknown";
+ counts[lang] = (counts[lang] || 0) + 1;
+ }
+ }
+ return counts;
+}
+
+export interface AttentionItem {
+ id: string;
+ type: "stale_decision" | "knowledge_silo" | "ungoverned_hotspot" | "dead_code" | "proposed_decision";
+ title: string;
+ description: string;
+ severity: "high" | "medium" | "low";
+ href?: string;
+}
+
+/** Build attention items from existing API responses */
+export function buildAttentionItems(params: {
+ staleDecisions: Array<{ id: string; title: string; staleness_score: number }>;
+ proposedDecisions: Array<{ id: string; title: string }>;
+ ungovernedHotspots: string[];
+ siloModules: Array<{ module_path: string; primary_owner: string | null }>;
+ deadCodeSafe: Array<{ id: string; file_path: string; symbol_name: string | null; lines: number }>;
+}): AttentionItem[] {
+ const items: AttentionItem[] = [];
+
+ for (const d of params.staleDecisions.slice(0, 3)) {
+ items.push({
+ id: `stale-${d.id}`,
+ type: "stale_decision",
+ title: d.title,
+ description: `Staleness score: ${Math.round(d.staleness_score * 100)}%`,
+ severity: d.staleness_score > 0.7 ? "high" : "medium",
+ });
+ }
+
+ for (const h of params.ungovernedHotspots.slice(0, 3)) {
+ items.push({
+ id: `hotspot-${h}`,
+ type: "ungoverned_hotspot",
+ title: h.split("/").slice(-2).join("/"),
+ description: "High churn, no governing decision",
+ severity: "high",
+ });
+ }
+
+ for (const s of params.siloModules.slice(0, 3)) {
+ items.push({
+ id: `silo-${s.module_path}`,
+ type: "knowledge_silo",
+ title: s.module_path,
+ description: `Single owner: ${s.primary_owner ?? "unknown"}`,
+ severity: "medium",
+ });
+ }
+
+ const totalDeadLines = params.deadCodeSafe.reduce((sum, d) => sum + d.lines, 0);
+ if (params.deadCodeSafe.length > 0) {
+ items.push({
+ id: "dead-code-summary",
+ type: "dead_code",
+ title: `${params.deadCodeSafe.length} safe-to-delete findings`,
+ description: `${totalDeadLines} lines can be removed`,
+ severity: totalDeadLines > 500 ? "medium" : "low",
+ });
+ }
+
+ for (const p of params.proposedDecisions.slice(0, 2)) {
+ items.push({
+ id: `proposed-${p.id}`,
+ type: "proposed_decision",
+ title: p.title,
+ description: "Awaiting review",
+ severity: "low",
+ });
+ }
+
+ // Sort by severity
+ const order = { high: 0, medium: 1, low: 2 };
+ items.sort((a, b) => order[a.severity] - order[b.severity]);
+
+ return items;
+}
diff --git a/tests/unit/server/conftest.py b/tests/unit/server/conftest.py
index dfe23151a..b29f49f2b 100644
--- a/tests/unit/server/conftest.py
+++ b/tests/unit/server/conftest.py
@@ -106,6 +106,7 @@ async def app(test_engine, session_factory):
test_app.state.session_factory = session_factory
test_app.state.fts = fts
test_app.state.vector_store = vector_store
+ test_app.state.background_tasks = set() # Strong refs for background job tasks
yield test_app
await vector_store.close()
diff --git a/tests/unit/server/test_repos.py b/tests/unit/server/test_repos.py
index 221f2ff94..d0bb20ab6 100644
--- a/tests/unit/server/test_repos.py
+++ b/tests/unit/server/test_repos.py
@@ -2,6 +2,8 @@
from __future__ import annotations
+from unittest.mock import AsyncMock, patch
+
import pytest
from httpx import AsyncClient
@@ -72,7 +74,8 @@ async def test_update_repo(client: AsyncClient) -> None:
@pytest.mark.asyncio
async def test_sync_repo_returns_202(client: AsyncClient) -> None:
repo = await create_test_repo(client)
- resp = await client.post(f"/api/repos/{repo['id']}/sync")
+ with patch("repowise.server.routers.repos.execute_job", new_callable=AsyncMock):
+ resp = await client.post(f"/api/repos/{repo['id']}/sync")
assert resp.status_code == 202
data = resp.json()
assert "job_id" in data
@@ -88,7 +91,37 @@ async def test_sync_repo_not_found(client: AsyncClient) -> None:
@pytest.mark.asyncio
async def test_full_resync_returns_202(client: AsyncClient) -> None:
repo = await create_test_repo(client)
- resp = await client.post(f"/api/repos/{repo['id']}/full-resync")
+ with patch("repowise.server.routers.repos.execute_job", new_callable=AsyncMock):
+ resp = await client.post(f"/api/repos/{repo['id']}/full-resync")
assert resp.status_code == 202
data = resp.json()
assert "job_id" in data
+
+
+async def test_sync_duplicate_returns_409(client: AsyncClient) -> None:
+ """A second sync while one is pending/running returns 409."""
+ repo = await create_test_repo(client)
+
+ # Mock execute_job to prevent actual background pipeline run during tests
+ with patch("repowise.server.routers.repos.execute_job", new_callable=AsyncMock):
+ resp1 = await client.post(f"/api/repos/{repo['id']}/sync")
+ assert resp1.status_code == 202
+
+ # Second sync should be rejected (job is still pending/running)
+ resp2 = await client.post(f"/api/repos/{repo['id']}/sync")
+ assert resp2.status_code == 409
+ assert "already in progress" in resp2.json()["detail"].lower()
+
+
+async def test_full_resync_duplicate_returns_409(client: AsyncClient) -> None:
+ """A second full-resync while one is pending/running returns 409."""
+ repo = await create_test_repo(client)
+
+ with patch("repowise.server.routers.repos.execute_job", new_callable=AsyncMock):
+ resp1 = await client.post(f"/api/repos/{repo['id']}/full-resync")
+ assert resp1.status_code == 202
+
+ resp2 = await client.post(f"/api/repos/{repo['id']}/full-resync")
+ assert resp2.status_code == 409
diff --git a/tests/unit/test_git_indexer.py b/tests/unit/test_git_indexer.py
index fc8b0f434..ec1c9be4d 100644
--- a/tests/unit/test_git_indexer.py
+++ b/tests/unit/test_git_indexer.py
@@ -261,21 +261,15 @@ class TestStableClassification:
mock_repo = MagicMock()
- # Build 15 commits all older than 90 days
+ # Build 15 commits all older than 90 days.
+ # _index_file now uses repo.git.log with NUL-delimited format:
+ # \x00<sha>\x1f<author>\x1f<email>\x1f<unix_ts>\x1f<parents>\x1f<subject>
old_date = datetime.now(UTC) - timedelta(days=180)
- commits = [
- _make_commit(
- hexsha=f"sha{i:04d}",
- committed_datetime=old_date - timedelta(days=i),
- )
- for i in range(15)
- ]
- mock_repo.iter_commits.return_value = commits
-
- # Mock blame to return a simple result
- mock_repo.blame.return_value = [
- (_make_commit(author_name="Alice", author_email="[email protected]"), ["line"] * 100),
- ]
+ log_lines = []
+ for i in range(15):
+ ts = int((old_date - timedelta(days=i)).timestamp())
+ log_lines.append(f"\x00sha{i:04d}\x1fAlice\[email protected]\x1f{ts}\x1f\x1ffeat: old commit {i}")
+ mock_repo.git.log.return_value = "\n".join(log_lines)
meta = indexer._index_file("stable_file.py", mock_repo)
@@ -284,6 +278,163 @@ class TestStableClassification:
assert meta["is_stable"] is True
+# ---------------------------------------------------------------------------
+# 4b. test_numstat_parsing
+# ---------------------------------------------------------------------------
+
+
+class TestNumstatParsing:
+ """Validate the single-git-log numstat parser only counts the target file."""
+
+ def _build_log_output(self, file_path: str, entries: list[dict]) -> str:
+ """Build a mock git log --numstat output string.
+
+ Each entry: {sha, author, email, ts, parents, subject, numstat_lines}
+ where numstat_lines is a list of (added, deleted, path) tuples.
+ """
+ lines = []
+ for e in entries:
+ header = (
+ f"\x00{e['sha']}\x1f{e.get('author', 'Dev')}"
+ f"\x1f{e.get('email', '[email protected]')}"
+ f"\x1f{e['ts']}\x1f{e.get('parents', '')}"
+ f"\x1f{e.get('subject', 'some commit')}"
+ )
+ lines.append(header)
+ for added, deleted, path in e.get("numstat_lines", []):
+ lines.append(f"{added}\t{deleted}\t{path}")
+ lines.append("") # blank line between commits (git does this)
+ return "\n".join(lines)
+
+ def test_only_target_file_counted(self) -> None:
+ """Churn stats must only include the target file, not other files in the same commit."""
+ indexer = GitIndexer("/tmp/repo")
+ mock_repo = MagicMock()
+
+ now = datetime.now(UTC)
+ recent_ts = int((now - timedelta(days=5)).timestamp())
+
+ raw = self._build_log_output("src/app.py", [
+ {
+ "sha": "aaa11111",
+ "ts": recent_ts,
+ "subject": "feat: big change",
+ "numstat_lines": [
+ ("100", "50", "src/app.py"), # target: should count
+ ("500", "300", "src/other.py"), # not target: must NOT count
+ ("200", "100", "src/utils.py"), # not target: must NOT count
+ ],
+ },
+ ])
+ mock_repo.git.log.return_value = raw
+
+ meta = indexer._index_file("src/app.py", mock_repo)
+
+ assert meta["lines_added_90d"] == 100
+ assert meta["lines_deleted_90d"] == 50
+ assert meta["avg_commit_size"] == 150.0 # (100+50)/1
+
+ def test_binary_file_stats_ignored(self) -> None:
+ """Binary files emit '-' for added/deleted — should contribute 0."""
+ indexer = GitIndexer("/tmp/repo")
+ mock_repo = MagicMock()
+
+ recent_ts = int((datetime.now(UTC) - timedelta(days=5)).timestamp())
+
+ raw = self._build_log_output("icon.png", [
+ {
+ "sha": "bbb22222",
+ "ts": recent_ts,
+ "subject": "feat: add icon",
+ "numstat_lines": [
+ ("-", "-", "icon.png"),
+ ],
+ },
+ ])
+ mock_repo.git.log.return_value = raw
+
+ meta = indexer._index_file("icon.png", mock_repo)
+
+ assert meta["lines_added_90d"] == 0
+ assert meta["lines_deleted_90d"] == 0
+
+ def test_empty_output_returns_defaults(self) -> None:
+ """Empty git log output returns default meta without errors."""
+ indexer = GitIndexer("/tmp/repo")
+ mock_repo = MagicMock()
+ mock_repo.git.log.return_value = ""
+
+ meta = indexer._index_file("new_file.py", mock_repo)
+
+ assert meta["commit_count_total"] == 0
+ assert meta["lines_added_90d"] == 0
+
+ def test_malformed_header_skipped(self) -> None:
+ """Lines with fewer than 6 fields are gracefully skipped."""
+ indexer = GitIndexer("/tmp/repo")
+ mock_repo = MagicMock()
+
+ recent_ts = int((datetime.now(UTC) - timedelta(days=5)).timestamp())
+ # First record is malformed (only 3 fields), second is valid
+ raw = (
+ f"\x00badsha\x1fAlice\[email protected]\n" # only 3 fields
+ f"\x00goodsha\x1fBob\[email protected]\x1f{recent_ts}\x1f\x1ffeat: valid commit\n"
+ f"10\t5\ttest.py\n"
+ )
+ mock_repo.git.log.return_value = raw
+
+ meta = indexer._index_file("test.py", mock_repo)
+
+ assert meta["commit_count_total"] == 1
+ assert meta["lines_added_90d"] == 10
+
+ def test_merge_commit_detected(self) -> None:
+ """Commits with multiple parent SHAs are flagged as merge commits."""
+ indexer = GitIndexer("/tmp/repo")
+ mock_repo = MagicMock()
+
+ recent_ts = int((datetime.now(UTC) - timedelta(days=5)).timestamp())
+ raw = (
+ f"\x00sha1\x1fAlice\[email protected]\x1f{recent_ts}"
+ f"\x1fparent1 parent2\x1fMerge branch main\n"
+ f"5\t2\tmerged.py\n"
+ )
+ mock_repo.git.log.return_value = raw
+
+ meta = indexer._index_file("merged.py", mock_repo)
+
+ assert meta["merge_commit_count_90d"] == 1
+
+ def test_rename_tracking_with_follow(self) -> None:
+ """When follow_renames=True, numstat lines with old paths are counted."""
+ indexer = GitIndexer("/tmp/repo", follow_renames=True)
+ mock_repo = MagicMock()
+
+ recent_ts = int((datetime.now(UTC) - timedelta(days=5)).timestamp())
+ old_ts = int((datetime.now(UTC) - timedelta(days=30)).timestamp())
+
+ # Simulates --follow output: recent commit uses new name,
+ # older commit uses rename notation, oldest uses old name.
+ raw = (
+ f"\x00sha1\x1fAlice\[email protected]\x1f{recent_ts}\x1f\x1ffeat: update\n"
+ f"10\t3\tsrc/new_name.py\n"
+ f"\n"
+ f"\x00sha2\x1fAlice\[email protected]\x1f{old_ts}\x1f\x1frename file\n"
+ f"0\t0\t{{src/old_name.py => src/new_name.py}}\n"
+ f"\n"
+ f"\x00sha3\x1fAlice\[email protected]\x1f{old_ts - 86400}\x1f\x1ffeat: old work\n"
+ f"20\t5\tsrc/old_name.py\n"
+ )
+ mock_repo.git.log.return_value = raw
+
+ meta = indexer._index_file("src/new_name.py", mock_repo)
+
+ assert meta["commit_count_total"] == 3
+ # Both the new-name and old-name stats should be counted
+ assert meta["lines_added_90d"] == 10 + 20 # sha1 + sha3
+ assert meta["lines_deleted_90d"] == 3 + 5
+
+
# ---------------------------------------------------------------------------
# 5. test_git_unavailable_graceful
# ---------------------------------------------------------------------------