LicenseCheck - Automated Dependency License Scanning and Compliance Reports

Acceptance Criteria

GitHub Integration: done when user can install app and authorize repos without errors. Weekly Scan: done when cron job pulls package.json and identifies 10+ dependencies from a real repo. License Metadata: done when npm and PyPI queries return license data for 95%+ of dependencies. Policy Engine: done when user defines a rule (e.g., 'block GPL') and violations are caught. Dashboard: done when license pie chart and violation list load in under 2 seconds.

How to build it, step by step

1. Bootstrap app: npx create-next-app@latest licensecheck --typescript --app, then npm install @supabase/supabase-js @octokit/rest @octokit/webhooks stripe p-limit. 2. Supabase schema: create tables — users (id, github_id, email), repos (id, user_id, github_repo_id, full_name, enabled), scans (id, repo_id, scanned_at, status), dependencies (id, scan_id, name, version, ecosystem, spdx_license, is_direct), violations (id, scan_id, dependency_id, rule_triggered), policies (id, user_id, blocked_licenses text[], require_license bool). Enable RLS on all tables. 3. GitHub OAuth: configure Supabase Auth with GitHub provider, request scopes 'read:user repo'. On callback, store github_access_token in users table (encrypted). 4. Register GitHub App at github.com/settings/apps — set webhook URL to /api/github/webhook, request permissions: Contents (read), Metadata (read). Generate and store GITHUB_APP_PRIVATE_KEY and GITHUB_APP_ID in env. 5. GitHub App installation endpoint: build /api/github/install — on installation webhook event, use Octokit with app auth to list repos, upsert into repos table with installation_id. 6. Lock file parser: build /lib/parsers/npm.ts that reads package-lock.json from GitHub API (GET /repos/{owner}/{repo}/contents/package-lock.json), parses dependencies object, extracts name+version+resolved. Build /lib/parsers/python.ts for poetry.lock and requirements.txt. Mark direct vs. transitive dependencies. 7. Registry license fetcher: build /lib/registry/npm.ts — fetch https://registry.npmjs.org/{package}/{version}, extract .license field (SPDX string). If missing, fallback to fetching the package's GitHub repo URL and checking LICENSE file via raw.githubusercontent.com. Build /lib/registry/pypi.ts — fetch https://pypi.org/pypi/{package}/{version}/json, extract info.license. Use p-limit(10) to parallelize with max 10 concurrent requests. 8. SPDX classifier: build /lib/spdx.ts that maps raw license strings to canonical SPDX identifiers using the spdx-correct npm package (real package: npm install spdx-correct spdx-expression-parse). Classify into risk tiers: PERMISSIVE (MIT, Apache-2.0, BSD-*), WEAK_COPYLEFT (LGPL-*), STRONG_COPYLEFT (GPL-*, AGPL-*), PROPRIETARY, UNKNOWN. 9. Policy engine: build /lib/policy.ts — load user's policy from Supabase, iterate dependencies, flag violations where dependency.risk_tier is in policy.blocked_licenses or dependency.spdx_license is UNKNOWN and policy.require_license is true. Write violations to violations table. 10. Weekly cron via Vercel: add to vercel.json: {"crons": [{"path": "/api/jobs/weekly-scan", "schedule": "0 9 * * 1"}]}. In /api/jobs/weekly-scan, query all enabled repos, run the parse -> fetch -> classify -> policy-check pipeline for each, store scan results. 11. Slack alert: on violations detected, POST to user's configured Slack webhook URL using Slack Block Kit — include repo name, violation count, and a link to the dashboard. Build Slack connection UI in settings page (user pastes incoming webhook URL). 12. Dashboard: build /app/dashboard using Recharts (npm install recharts) for a pie chart of license distribution. Fetch scan history and violations from Supabase via server component. Add CSV export endpoint /api/export/scan/[scanId] that streams a CSV of all dependencies + licenses. 13. Stripe billing: create two products in Stripe dashboard ($129/mo Starter, $299/mo Pro). Build /api/billing/checkout (create Stripe Checkout session) and /api/billing/webhook (handle checkout.session.completed to set user.plan in Supabase). Gate weekly scan frequency and repo count by plan. 14. Deploy: push to GitHub, connect to Vercel, set all env vars (GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, SUPABASE_URL, SUPABASE_SERVICE_KEY, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET). Verify Vercel cron appears in dashboard under Settings > Cron Jobs.