baseline-chekto

setup automatic alerts for deprecated checks

Comment

Inspiration

What it does

How we built it

Challenges we ran into

Accomplishments that we're proud of

What we learned# Baseline Hack - Project Overview

🎯 Project Summary

Baseline Hack is an automated web development tool that monitors GitHub repositories for deprecated web features using Google's Baseline tooling. It provides intelligent analysis, automated issue creation, and comprehensive remediation guidance to help developers maintain modern web standards and improve code quality.

The application serves as a bridge between Google's Baseline initiative and practical development workflows, offering real-time monitoring, detailed analysis, and actionable recommendations for modernizing web applications.

🚀 Core Features

1. Automated Deprecated Feature Detection

  • Smart Scanning: Automatically scans repositories for deprecated web features using pattern matching and Google's Baseline data
  • Multi-format Support: Analyzes JavaScript, TypeScript, React, Vue, Svelte, HTML, and CSS files
  • Intelligent Filtering: Excludes build artifacts, dependencies, and version control files
  • Real-time Analysis: Provides immediate feedback on code quality and modern web standards compliance

2. Comprehensive Issue Management

  • Automated GitHub Issues: Creates detailed GitHub issues with categorized deprecated features
  • Smart Categorization: Groups issues by severity (high, medium, low) and feature type
  • Rich Documentation: Includes MDN links, alternatives, and migration guidance
  • Issue Updates: Updates existing issues instead of creating duplicates
  • File-level Comments: Provides specific line numbers and affected code sections

3. Advanced Code Analysis Engine

  • Pattern Recognition: Detects common deprecated patterns like document.write(), eval(), jQuery usage, and CSS float layouts
  • Context-aware Analysis: Understands code context and provides relevant alternatives
  • Confidence Scoring: Calculates confidence scores based on detection accuracy
  • Multi-file Analysis: Processes entire repositories with intelligent file filtering

4. Real-time Dashboard

  • Live Monitoring: Real-time updates on scan progress and repository health
  • Statistics Overview: Displays scan history, confidence scores, and issue resolution rates
  • Repository Management: Easy repository selection and connection interface
  • Timeline View: Visual representation of scan history and trends
  • Empty State Handling: Guided onboarding for new users

5. Smart Notifications

  • Email Alerts: Automated email notifications for scan results and issue creation
  • In-app Notifications: Real-time dashboard updates and status changes
  • Configurable Preferences: Customizable notification settings per user

6. Secure Authentication & Integration

  • GitHub OAuth: Secure authentication with minimal required permissions
  • Webhook Integration: Automatic webhook setup for repository monitoring
  • Token Management: Encrypted storage of GitHub access tokens
  • Permission Scoping: Requests only necessary repository access

🛠️ Technology Stack

Frontend Technologies

  • Next.js 15: React framework with App Router for modern web development
  • React 19: Latest React version with enhanced performance and features
  • TypeScript: Type-safe development with comprehensive type definitions
  • Tailwind CSS 4.1: Utility-first CSS framework for rapid UI development
  • Radix UI: Accessible component primitives for complex UI elements
  • Lucide React: Modern icon library for consistent visual design

Backend & Database

  • Convex: Real-time database and backend-as-a-service platform
  • Convex Functions: Serverless functions for API endpoints and data processing
  • Real-time Subscriptions: Live data updates across the application
  • Type-safe Queries: End-to-end type safety from database to frontend

Authentication & Security

  • BetterAuth: Modern authentication library with GitHub OAuth integration
  • Encrypted Storage: Secure storage of sensitive tokens and credentials
  • Webhook Verification: GitHub webhook signature validation
  • Environment Security: Comprehensive environment variable protection

External Integrations

  • GitHub API: Repository access, file analysis, and issue management
  • OpenAI GPT-5-nano: AI-powered code analysis and pattern recognition
  • Resend: Email service for notifications and alerts
  • Octokit: GitHub API client for reliable repository interactions

Development Tools

  • pnpm: Fast, efficient package manager for dependency management
  • ESLint: Code linting and quality assurance
  • PostCSS: CSS processing and optimization
  • Autoprefixer: Automatic vendor prefix management

🏗️ Architecture Overview

Application Structure

src/
├── app/                    # Next.js App Router pages
│   ├── api/               # API routes for backend functionality
│   ├── auth/              # Authentication pages
│   └── dashboard/         # Main application dashboard
├── components/            # Reusable React components
│   ├── dashboard/         # Dashboard-specific components
│   ├── providers/         # Context providers
│   └── ui/               # Base UI components
├── hooks/                # Custom React hooks
└── lib/                  # Core business logic and utilities
    ├── baseline-detector.ts    # Deprecated feature detection
    ├── code-analysis.ts        # Code analysis engine
    ├── issue-generator.ts      # GitHub issue creation
    └── auth.ts                 # Authentication utilities

Database Schema

The application uses Convex with the following main entities:

  • Users: User accounts with GitHub integration and preferences
  • Repositories: Monitored repositories with webhook configuration
  • Migrations: Scan jobs and their results (legacy naming)
  • Breaking Changes: Detected deprecated features and remediation info
  • Affected Files: File-level analysis results
  • Notifications: User alerts and system messages
  • Webhook Events: GitHub webhook processing and tracking

API Architecture

  • RESTful Endpoints: Standard HTTP methods for repository operations
  • Real-time Updates: Convex subscriptions for live data
  • Error Handling: Comprehensive error management and user feedback
  • Rate Limiting: GitHub API rate limit management

🔍 Key Functionality

Baseline Detection Process

  1. Repository Analysis: Fetches repository files using GitHub API
  2. Pattern Matching: Scans code for deprecated web feature patterns
  3. Context Analysis: Analyzes code context and usage patterns
  4. Confidence Scoring: Calculates detection confidence based on multiple factors
  5. Issue Generation: Creates comprehensive GitHub issues with remediation guidance

Supported Deprecated Features

  • JavaScript: document.write(), eval(), var declarations, jQuery usage
  • Async Patterns: Incorrect forEach with async/await usage
  • Security Issues: innerHTML with user input, XSS vulnerabilities
  • Legacy APIs: XMLHttpRequest, deprecated DOM methods
  • CSS: Float-based layouts, outdated CSS properties

Issue Generation Features

  • Comprehensive Reports: Detailed analysis with severity categorization
  • Code Examples: Before/after code snippets for migration
  • Resource Links: MDN documentation and modern alternatives
  • File-level Details: Specific line numbers and affected code sections
  • Automated Labels: Smart labeling for issue organization

🎨 User Experience

Dashboard Interface

  • Modern Design: Clean, dark-themed interface with gradient accents
  • Responsive Layout: Optimized for desktop and mobile devices
  • Real-time Updates: Live data updates without page refreshes
  • Intuitive Navigation: Clear information hierarchy and user flows

Repository Management

  • Easy Connection: One-click repository selection and webhook setup
  • Scan Controls: Manual scan triggers with progress indicators
  • Status Monitoring: Real-time scan status and result tracking
  • History Tracking: Complete scan history with detailed results

Issue Integration

  • Seamless GitHub Integration: Direct links to created issues
  • Rich Issue Content: Comprehensive issue descriptions with formatting
  • Automated Updates: Issue updates instead of duplicates
  • Progress Tracking: Issue resolution monitoring and statistics

🔧 Configuration & Setup

Environment Requirements

  • Node.js 18+ with pnpm package manager
  • GitHub account with repository access
  • OpenAI API key for AI-powered analysis
  • Resend API key for email notifications
  • Convex deployment for backend services

Deployment Architecture

  • Frontend: Next.js application with static optimization
  • Backend: Convex serverless functions and real-time database
  • External Services: GitHub, OpenAI, and Resend API integrations
  • Security: Encrypted token storage and webhook verification

📊 Performance & Scalability

Optimization Features

  • File Filtering: Intelligent file type and size filtering
  • Batch Processing: Efficient handling of large repositories
  • Caching: Strategic caching of analysis results
  • Rate Limiting: GitHub API rate limit management
  • Error Recovery: Robust error handling and retry mechanisms

Scalability Considerations

  • Serverless Architecture: Automatic scaling with Convex
  • Efficient Queries: Optimized database queries and indexing
  • Background Processing: Asynchronous scan processing
  • Resource Management: Memory and CPU optimization for large repositories

🛡️ Security & Privacy

Data Protection

  • Encrypted Storage: All sensitive data encrypted at rest
  • Secure Transmission: HTTPS enforcement and secure API calls
  • Token Management: Secure GitHub token storage and rotation
  • Access Control: Minimal permission scoping for GitHub integration

Privacy Features

  • Data Minimization: Only necessary data collection and storage
  • User Control: Configurable privacy settings and data deletion
  • Audit Logging: Comprehensive logging for security monitoring
  • Compliance: GDPR and privacy best practices implementation

🚀 Future Enhancements

Planned Features

  • Multi-language Support: Extended support for Python, Go, Rust, and other languages
  • Advanced AI Analysis: Enhanced pattern recognition with machine learning
  • Team Collaboration: Multi-user repository management and sharing
  • CI/CD Integration: Automated scanning in continuous integration pipelines
  • Custom Rules: User-defined detection patterns and rules
  • Performance Metrics: Detailed performance impact analysis

Integration Roadmap

  • GitLab Support: Extended support for GitLab repositories
  • Slack Integration: Team notifications and collaboration features
  • VS Code Extension: Direct IDE integration for real-time feedback
  • API Access: Public API for third-party integrations

Baseline Hack represents a comprehensive solution for modern web development challenges, combining Google's Baseline initiative with practical development workflows to help teams maintain high-quality, modern web applications.

What's next for baseline-chekto

Built With

Share this project:

Updates