@theihtisham/dev-pulse 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DevPulse Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# Dev Pulse
+
+Developer productivity metrics dashboard
+
+## Installation
+
+```bash
+npm install @theihtisham/dev-pulse
+```
+
+## Usage
+
+```typescript
+import { } from '@theihtisham/dev-pulse';
+```
+
+## Features
+
+- Written in TypeScript with full type definitions
+- Zero external dependencies (minimal footprint)
+- Event-driven architecture
+- Comprehensive test suite
+
+## API
+
+### Quick Start
+
+```typescript
+import { } from '@theihtisham/dev-pulse';
+
+// Initialize and use the package
+```
+
+## Configuration
+
+Configuration options and their defaults:
+
+```typescript
+const config = {
+  // Add configuration options here
+};
+```
+
+## Examples
+
+See the `tests/` directory for usage examples.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Lint
+npm run lint
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Author
+
+**ihtisham**
+
+- GitHub: [https://github.com/ihtisham](https://github.com/ihtisham)
+- npm: [@theihtisham](https://www.npmjs.com/~theihtisham)

package/devpulse/__init__.py

@@ -0,0 +1,4 @@
+"""DevPulse - AI-powered developer productivity dashboard."""
+
+__version__ = "1.0.0"
+__author__ = "DevPulse Contributors"

package/devpulse/api/__init__.py

@@ -0,0 +1 @@
+"""FastAPI web API package for DevPulse."""

package/devpulse/api/app.py

@@ -0,0 +1,371 @@
+"""FastAPI application for DevPulse REST API."""
+
+import os
+from datetime import datetime
+from typing import Any, Optional
+
+from fastapi import FastAPI, HTTPException, Query
+from fastapi.responses import HTMLResponse, JSONResponse
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+
+from devpulse.core.database import Database
+from devpulse.core.analytics import AnalyticsEngine
+from devpulse.core.report_generator import ReportGenerator
+
+app = FastAPI(
+    title="DevPulse API",
+    description="AI-powered developer productivity dashboard with GitHub integration.",
+    version="1.0.0",
+    docs_url="/docs",
+    redoc_url="/redoc",
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+def _get_db() -> Database:
+    return Database()
+
+
+def _get_engine() -> AnalyticsEngine:
+    return AnalyticsEngine(db=_get_db())
+
+
+def _get_report_gen() -> ReportGenerator:
+    return ReportGenerator(db=_get_db())
+
+
+# ── Request/Response models ──────────────────────────────────────────
+
+class GoalCreate(BaseModel):
+    title: str
+    description: str = ""
+    target_value: float
+    metric: str
+    deadline: Optional[str] = None
+
+
+class SprintSnapshot(BaseModel):
+    sprint_name: str
+    total_points: float
+    completed_points: float
+    added_points: float = 0.0
+
+
+class QualitySnapshot(BaseModel):
+    repo: str
+    test_coverage: float = 0.0
+    open_bugs: int = 0
+    tech_debt_score: float = 0.0
+    lines_added: int = 0
+    lines_removed: int = 0
+    files_changed: int = 0
+
+
+class HealthResponse(BaseModel):
+    overall_score: float
+    workload_balance: float
+    burnout_risk: dict[str, float]
+    collaboration_score: float
+    velocity_trend: str
+    recommendations: list[str]
+
+
+class MessageResponse(BaseModel):
+    message: str
+    detail: Optional[str] = None
+
+
+# ── Health check ─────────────────────────────────────────────────────
+
+@app.get("/", tags=["health"])
+def root() -> dict[str, str]:
+    """API health check."""
+    return {
+        "name": "DevPulse API",
+        "version": "1.0.0",
+        "status": "healthy",
+        "timestamp": datetime.utcnow().isoformat(),
+    }
+
+
+# ── Commits ──────────────────────────────────────────────────────────
+
+@app.get("/api/commits", tags=["commits"])
+def list_commits(
+    repo: Optional[str] = Query(None),
+    author: Optional[str] = Query(None),
+    since: Optional[str] = Query(None),
+    limit: int = Query(100, ge=1, le=1000),
+) -> list[dict[str, Any]]:
+    """List commits with optional filters."""
+    db = _get_db()
+    return db.get_commits(repo=repo, author=author, since=since, limit=limit)
+
+
+@app.get("/api/commits/heatmap", tags=["commits"])
+def commit_heatmap(
+    author: Optional[str] = Query(None),
+    days: int = Query(365, ge=7, le=730),
+) -> list[dict[str, Any]]:
+    """Get daily commit counts for heatmap visualization."""
+    db = _get_db()
+    return db.get_commit_count_by_day(author=author, days=days)
+
+
+# ── Pull Requests ────────────────────────────────────────────────────
+
+@app.get("/api/pull-requests", tags=["pull-requests"])
+def list_pull_requests(
+    repo: Optional[str] = Query(None),
+    author: Optional[str] = Query(None),
+    state: Optional[str] = Query(None),
+    since: Optional[str] = Query(None),
+    limit: int = Query(100, ge=1, le=500),
+) -> list[dict[str, Any]]:
+    """List pull requests with optional filters."""
+    db = _get_db()
+    return db.get_pull_requests(repo=repo, author=author, state=state, since=since, limit=limit)
+
+
+# ── Issues ───────────────────────────────────────────────────────────
+
+@app.get("/api/issues", tags=["issues"])
+def list_issues(
+    repo: Optional[str] = Query(None),
+    state: Optional[str] = Query(None),
+    since: Optional[str] = Query(None),
+    limit: int = Query(100, ge=1, le=500),
+) -> list[dict[str, Any]]:
+    """List issues with optional filters."""
+    db = _get_db()
+    return db.get_issues(repo=repo, state=state, since=since, limit=limit)
+
+
+# ── Reviews ──────────────────────────────────────────────────────────
+
+@app.get("/api/reviews", tags=["reviews"])
+def list_reviews(
+    repo: Optional[str] = Query(None),
+    author: Optional[str] = Query(None),
+    since: Optional[str] = Query(None),
+    limit: int = Query(100, ge=1, le=500),
+) -> list[dict[str, Any]]:
+    """List code reviews with optional filters."""
+    db = _get_db()
+    return db.get_reviews(repo=repo, author=author, since=since, limit=limit)
+
+
+# ── Metrics ──────────────────────────────────────────────────────────
+
+@app.get("/api/metrics/{author}", tags=["metrics"])
+def get_developer_metrics(
+    author: str,
+    days: int = Query(30, ge=1, le=365),
+    repo: Optional[str] = Query(None),
+) -> dict[str, Any]:
+    """Get comprehensive metrics for a developer."""
+    engine = _get_engine()
+    metrics = engine.developer_metrics(author=author, days=days, repo=repo)
+    return metrics.model_dump()
+
+
+@app.get("/api/metrics", tags=["metrics"])
+def get_team_metrics(
+    days: int = Query(30, ge=1, le=365),
+    repo: Optional[str] = Query(None),
+) -> list[dict[str, Any]]:
+    """Get metrics for all team members."""
+    engine = _get_engine()
+    team = engine.team_metrics(days=days, repo=repo)
+    return [m.model_dump() for m in team]
+
+
+# ── Team Health ──────────────────────────────────────────────────────
+
+@app.get("/api/health", tags=["health"], response_model=HealthResponse)
+def team_health(
+    days: int = Query(30, ge=1, le=365),
+    repo: Optional[str] = Query(None),
+) -> HealthResponse:
+    """Analyze team health and burnout risk."""
+    engine = _get_engine()
+    health = engine.team_health(days=days, repo=repo)
+    return HealthResponse(
+        overall_score=health.overall_score,
+        workload_balance=health.workload_balance,
+        burnout_risk=health.burnout_risk,
+        collaboration_score=health.collaboration_score,
+        velocity_trend=health.velocity_trend,
+        recommendations=health.recommendations,
+    )
+
+
+# ── AI Insights ──────────────────────────────────────────────────────
+
+@app.get("/api/insights", tags=["insights"])
+def get_insights(
+    days: int = Query(30, ge=1, le=365),
+    repo: Optional[str] = Query(None),
+) -> list[dict[str, str]]:
+    """Get AI-powered insights and recommendations."""
+    engine = _get_engine()
+    return engine.generate_insights(days=days, repo=repo)
+
+
+# ── Goals ────────────────────────────────────────────────────────────
+
+@app.get("/api/goals", tags=["goals"])
+def list_goals(status: Optional[str] = Query(None)) -> list[dict[str, Any]]:
+    """List goals."""
+    db = _get_db()
+    return db.get_goals(status=status)
+
+
+@app.post("/api/goals", tags=["goals"], status_code=201)
+def create_goal(goal: GoalCreate) -> dict[str, Any]:
+    """Create a new goal."""
+    db = _get_db()
+    gid = db.upsert_goal(goal.model_dump())
+    return {"id": gid, **goal.model_dump()}
+
+
+@app.delete("/api/goals/{goal_id}", tags=["goals"])
+def delete_goal(goal_id: int) -> MessageResponse:
+    """Delete a goal."""
+    db = _get_db()
+    if db.delete_goal(goal_id):
+        return MessageResponse(message=f"Goal {goal_id} deleted.")
+    raise HTTPException(status_code=404, detail=f"Goal {goal_id} not found.")
+
+
+@app.get("/api/goals/coach", tags=["goals"])
+def goal_coaching(goal_id: Optional[int] = Query(None)) -> list[dict[str, Any]]:
+    """Get AI coaching for goals."""
+    engine = _get_engine()
+    return engine.goal_coaching(goal_id=goal_id)
+
+
+# ── Sprints ──────────────────────────────────────────────────────────
+
+@app.post("/api/sprints/snapshot", tags=["sprints"], status_code=201)
+def create_sprint_snapshot(snapshot: SprintSnapshot) -> MessageResponse:
+    """Record a sprint snapshot."""
+    db = _get_db()
+    db.save_sprint_snapshot({
+        "sprint_name": snapshot.sprint_name,
+        "total_points": snapshot.total_points,
+        "completed_points": snapshot.completed_points,
+        "remaining_points": snapshot.total_points - snapshot.completed_points,
+        "added_points": snapshot.added_points,
+    })
+    return MessageResponse(message=f"Sprint snapshot recorded for '{snapshot.sprint_name}'.")
+
+
+@app.get("/api/sprints/{sprint_name}/burndown", tags=["sprints"])
+def sprint_burndown(sprint_name: str) -> list[dict[str, Any]]:
+    """Get burndown data for a sprint."""
+    engine = _get_engine()
+    return engine.sprint_burndown(sprint_name)
+
+
+@app.get("/api/sprints/{sprint_name}/predict", tags=["sprints"])
+def predict_sprint(
+    sprint_name: str,
+    total: float = Query(...),
+    elapsed: int = Query(...),
+    duration: int = Query(...),
+) -> dict[str, Any]:
+    """Predict sprint completion."""
+    engine = _get_engine()
+    return engine.predict_sprint_completion(sprint_name, total, elapsed, duration)
+
+
+# ── Code Quality ─────────────────────────────────────────────────────
+
+@app.post("/api/quality/snapshot", tags=["quality"], status_code=201)
+def create_quality_snapshot(snapshot: QualitySnapshot) -> MessageResponse:
+    """Record a code quality snapshot."""
+    db = _get_db()
+    db.save_quality_snapshot(snapshot.model_dump())
+    return MessageResponse(message=f"Quality snapshot recorded for '{snapshot.repo}'.")
+
+
+@app.get("/api/quality", tags=["quality"])
+def code_quality_trends(
+    repo: Optional[str] = Query(None),
+    days: int = Query(90, ge=1, le=365),
+) -> list[dict[str, Any]]:
+    """Get code quality trends."""
+    engine = _get_engine()
+    trends = engine.code_quality_trend(repo=repo, days=days)
+    return [t.model_dump() for t in trends]
+
+
+@app.get("/api/quality/score", tags=["quality"])
+def quality_score(
+    repo: str = Query(..., description="Repository full name (e.g. owner/repo)"),
+    days: int = Query(30, ge=1, le=365),
+) -> dict[str, Any]:
+    """Compute aggregate quality score for a repo."""
+    engine = _get_engine()
+    return engine.compute_quality_score(repo=repo, days=days)
+
+
+# ── Reports ──────────────────────────────────────────────────────────
+
+@app.get("/api/reports/daily", tags=["reports"])
+def daily_report(
+    date: Optional[str] = Query(None),
+    author: Optional[str] = Query(None),
+    repo: Optional[str] = Query(None),
+    format: str = Query("json", regex="^(json|markdown|html)$"),
+) -> Any:
+    """Generate a daily report."""
+    gen = _get_report_gen()
+    data = gen.daily_report(target_date=date, author=author, repo=repo)
+    if format == "html":
+        return HTMLResponse(content=gen.to_html(data, "daily"))
+    if format == "markdown":
+        return JSONResponse(content={"markdown": gen.to_markdown(data, "daily")})
+    return data
+
+
+@app.get("/api/reports/weekly", tags=["reports"])
+def weekly_report(
+    week_start: Optional[str] = Query(None),
+    repo: Optional[str] = Query(None),
+    format: str = Query("json", regex="^(json|markdown|html)$"),
+) -> Any:
+    """Generate a weekly report."""
+    gen = _get_report_gen()
+    data = gen.weekly_report(week_start=week_start, repo=repo)
+    if format == "html":
+        return HTMLResponse(content=gen.to_html(data, "weekly"))
+    if format == "markdown":
+        return JSONResponse(content={"markdown": gen.to_markdown(data, "weekly")})
+    return data
+
+
+@app.get("/api/reports/monthly", tags=["reports"])
+def monthly_report(
+    year: Optional[int] = Query(None),
+    month: Optional[int] = Query(None),
+    repo: Optional[str] = Query(None),
+    format: str = Query("json", regex="^(json|markdown|html)$"),
+) -> Any:
+    """Generate a monthly report."""
+    gen = _get_report_gen()
+    data = gen.monthly_report(year=year, month=month, repo=repo)
+    if format == "html":
+        return HTMLResponse(content=gen.to_html(data, "monthly"))
+    if format == "markdown":
+        return JSONResponse(content={"markdown": gen.to_markdown(data, "monthly")})
+    return data

package/devpulse/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for DevPulse."""

package/devpulse/cli/dashboard.py

@@ -0,0 +1,131 @@
+"""Interactive terminal dashboard for DevPulse."""
+
+from typing import Optional
+
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.layout import Layout
+from rich.text import Text
+
+from devpulse.core.database import Database
+from devpulse.core.analytics import AnalyticsEngine
+from devpulse.core.report_generator import ReportGenerator
+from devpulse.cli.render import render_header, render_heatmap, render_insight_card
+
+
+def dashboard_cmd(
+    author: Optional[str] = None,
+    days: int = 30,
+    repo: Optional[str] = None,
+) -> None:
+    """Launch the full interactive terminal dashboard."""
+    console = Console()
+    db = Database()
+    engine = AnalyticsEngine(db=db)
+    report_gen = ReportGenerator(db=db)
+
+    render_header(console)
+
+    # ── Section 1: Summary ───────────────────────────────────────────
+    console.rule("[bold cyan]Overview[/bold cyan]")
+
+    daily = report_gen.daily_report(author=author, repo=repo)
+    console.print(f"\n  Date: [bold]{daily['date']}[/bold]")
+    console.print(f"  {daily['summary']}\n")
+
+    # ── Section 2: Team Metrics ──────────────────────────────────────
+    console.rule("[bold cyan]Team Metrics[/bold cyan]")
+    console.print()
+
+    team = engine.team_metrics(days=days, repo=repo)
+    if team:
+        table = Table(show_header=True, header_style="bold cyan", expand=True)
+        table.add_column("Developer", style="white", min_width=15)
+        table.add_column("Commits", justify="right")
+        table.add_column("C/D", justify="right", style="dim")
+        table.add_column("PRs", justify="right")
+        table.add_column("Reviews", justify="right")
+        table.add_column("Merge(h)", justify="right")
+        table.add_column("+/- Lines", justify="right")
+
+        for m in team[:10]:
+            table.add_row(
+                m.author,
+                str(m.commits_count),
+                str(m.commits_per_day),
+                str(m.prs_created),
+                str(m.reviews_given),
+                str(m.avg_pr_merge_time_hours),
+                f"+{m.lines_added}/-{m.lines_removed}",
+            )
+        console.print(table)
+    else:
+        console.print("[dim]No team data yet. Run 'devpulse sync' to fetch data.[/dim]")
+
+    # ── Section 3: Team Health ───────────────────────────────────────
+    console.rule("[bold cyan]Team Health[/bold cyan]")
+    console.print()
+
+    health = engine.team_health(days=days, repo=repo)
+    score_color = "green" if health.overall_score >= 70 else "yellow" if health.overall_score >= 40 else "red"
+    console.print(f"  Health Score: [{score_color}]{health.overall_score}/100[/{score_color}]")
+    console.print(f"  Workload Balance: {health.workload_balance:.0%}")
+    console.print(f"  Collaboration: {health.collaboration_score:.0%}")
+    console.print(f"  Velocity: {health.velocity_trend}")
+
+    if health.burnout_risk:
+        console.print("\n  [bold]Burnout Risk:[/bold]")
+        for name, risk in sorted(health.burnout_risk.items(), key=lambda x: x[1], reverse=True):
+            color = "red" if risk >= 0.6 else "yellow" if risk >= 0.3 else "green"
+            bar_len = int(risk * 20)
+            bar = "#" * bar_len + "-" * (20 - bar_len)
+            console.print(f"    {name:<15} [{color}]{bar}[/{color}] {risk:.0%}")
+
+    # ── Section 4: AI Insights ───────────────────────────────────────
+    console.rule("[bold cyan]AI Insights[/bold cyan]")
+    console.print()
+
+    insights = engine.generate_insights(days=days, repo=repo)
+    for i, insight in enumerate(insights, 1):
+        render_insight_card(console, insight, i)
+
+    # ── Section 5: Goals ─────────────────────────────────────────────
+    goals = db.get_goals(status="active")
+    if goals:
+        console.rule("[bold cyan]Active Goals[/bold cyan]")
+        console.print()
+        goal_table = Table(show_header=True, header_style="bold cyan")
+        goal_table.add_column("Goal", style="white")
+        goal_table.add_column("Metric")
+        goal_table.add_column("Progress", justify="right")
+        goal_table.add_column("Deadline")
+        for g in goals:
+            pct = (g["current_value"] / g["target_value"] * 100) if g["target_value"] > 0 else 0
+            color = "green" if pct >= 75 else "yellow" if pct >= 25 else "red"
+            goal_table.add_row(
+                g["title"],
+                g["metric"],
+                f"[{color}]{pct:.0%}[/{color}]",
+                g.get("deadline", "-"),
+            )
+        console.print(goal_table)
+
+    # ── Section 6: Heatmap ───────────────────────────────────────────
+    console.rule("[bold cyan]Activity Heatmap[/bold cyan]")
+    console.print()
+
+    heatmap_data = engine.activity_heatmap(author=author, days=90)
+    if heatmap_data:
+        render_heatmap(console, heatmap_data, days=90)
+    else:
+        console.print("[dim]No activity data. Run 'devpulse sync' to fetch commits.[/dim]")
+
+    # ── Section 7: Recommendations ───────────────────────────────────
+    console.rule("[bold cyan]Recommendations[/bold cyan]")
+    console.print()
+    for rec in health.recommendations:
+        console.print(f"  -> {rec}")
+
+    console.print()
+    console.print("[dim]Run 'devpulse sync' to refresh data | 'devpulse --help' for all commands[/dim]")