shipwarden 0.0.0-stage → 0.2.0

package/src/checklist.js

@@ -0,0 +1,255 @@
+// Launch checklist: things AI-built apps commonly ship without. These are not security
+// findings: they never fail a build, and each check only runs when it applies to the app.
+import { isServerEndpoint, lineAt } from './util.js';
+
+const CODE = /\.[cm]?[jt]sx?$|\.(vue|svelte|astro)$/;
+const PAGES = /\.[cm]?[jt]sx?$|\.(vue|svelte|astro|html|mdx?)$/;
+const HEAD_FILES = /(^|\/)(index\.html|(src\/)?app\/layout\.[jt]sx?|pages\/_(document|app)\.[jt]sx?|app\/root\.[jt]sx?|src\/app\.html|nuxt\.config\.[jt]s|src\/layouts\/\w+\.astro|(public\/)?(manifest|site)\.(json|webmanifest))$/;
+
+/** First match of `re` in files whose path matches `filter`, as a location. */
+function locate(files, re, filter = CODE) {
+  for (const f of files) {
+    if (!filter.test(f.path)) continue;
+    const m = re.exec(f.content);
+    if (m) return { file: f.path, line: lineAt(f.content, m.index) };
+  }
+  return null;
+}
+
+function signals(files, ctx) {
+  const dep = (re) => [...ctx.deps].some((d) => re.test(d));
+  // A sign-in that only exists on an admin page doesn't mean the app has user accounts.
+  const userFacing = files.filter((f) => !/(^|\/)[^/]*admin[^/]*(\/|$)/i.test(f.path));
+  const inCode = (re) => !!locate(userFacing, re);
+  const hostedAuthUi = dep(/^@clerk\/|^@auth0\/|^@kinde-oss\/|^@workos-inc\//);
+  const accounts =
+    hostedAuthUi ||
+    dep(/^next-auth$|^@auth\/|^better-auth$|^lucia$/) ||
+    inCode(/\.auth\.(signUp|signIn\w*)\s*\(|createUserWithEmailAndPassword|signInWithEmailAndPassword|signInWithPopup|signInWithRedirect/);
+  return {
+    hostedAuthUi,
+    accounts,
+    passwordAuth: inCode(/signInWithPassword|createUserWithEmailAndPassword|signInWithEmailAndPassword|CredentialsProvider|Credentials\(\s*\{|\.auth\.signUp\s*\(\s*\{[^}]*password/),
+    payments: dep(/^stripe$|^@stripe\/|^@lemonsqueezy\/|^@paddle\/|^@polar-sh\/|^razorpay$|^@paypal\//),
+    analytics: dep(/posthog|^@vercel\/analytics$|mixpanel|amplitude|^react-ga|^@next\/third-parties$|plausible|^@segment\/|umami|hotjar/i) || inCode(/googletagmanager\.com|\bgtag\s*\(/),
+  };
+}
+
+const exists = (ctx, re) => ctx.paths.some((p) => re.test(p));
+
+const AI_CALL =
+  /(?:from\s+|import\s*\(\s*|require\(\s*)['"](?:npm:|jsr:|https?:\/\/esm\.sh\/)?(?:openai|@anthropic-ai\/sdk|ai|@ai-sdk\/[\w-]+|groq-sdk|replicate|@google\/genai|@google\/generative-ai|@mistralai\/mistralai|cohere-ai)(?:@[^'"/]*)?(?:\/[^'"]*)?['"]|api\.openai\.com|api\.anthropic\.com|generativelanguage\.googleapis\.com|openrouter\.ai\/api|ai\.gateway\.lovable\.dev/;
+const RATE_LIMIT = /rate.?limit|ratelimit|limiter|throttl|arcjet|botid|turnstile|recaptcha|hcaptcha|usage.?limit|quota|credits?\b|max.?requests|requests?.?per/i;
+
+const BOILERPLATE = [
+  { re: /<title>\s*(?:Vite \+ React(?: \+ TS)?|Vite App|React App)\s*<\/title>|"(?:short_)?name"\s*:\s*"(?:React App|Create React App Sample)"/, label: 'the starter template title' },
+  { re: /Create Next App|Generated by create next app/, label: 'the "Create Next App" title' },
+  { re: /Lovable App|Lovable Generated Project|lovable\.dev\/opengraph-image|@lovable_dev/, label: "Lovable's default title, description or preview image" },
+  { re: /['"`]v0 App['"`]|Created with v0/, label: 'the default v0 title' },
+  { re: /href=["']\/vite\.svg["']/, label: "Vite's logo as the favicon" },
+];
+
+export const CHECKS = [
+  {
+    id: 'not-found-page',
+    title: '404 page',
+    missing: 'No 404 page',
+    applies: (s, ctx) => ctx.app,
+    priority: (s, ctx) => (ctx.kind === 'spa' ? 'must' : 'should'),
+    check(files, ctx) {
+      const byKind = {
+        next: /(^|\/)(src\/)?app\/not-found\.[jt]sx?$|(^|\/)(src\/)?pages\/404\.[jt]sx?$/,
+        sveltekit: /(^|\/)src\/routes\/\+error\.svelte$/,
+        nuxt: /(^|\/)error\.vue$/,
+        astro: /(^|\/)src\/pages\/404\.(astro|mdx?|html)$/,
+        remix: /(^|\/)app\/routes\/(\$|\[\$\]|404)\.[jt]sx?$/,
+      };
+      if (byKind[ctx.kind]) return exists(ctx, byKind[ctx.kind]);
+      return (
+        exists(ctx, /(^|\/)404\.html$|(^|\/)(NotFound|not-found|404)\.[a-z]+$/i) ||
+        !!locate(files, /path\s*[:=]\s*\{?\s*["'`]\/?\*["'`]|notFoundComponent|:pathMatch\(\.\*\)/)
+      );
+    },
+    why: (s, ctx) =>
+      ctx.kind === 'spa'
+        ? 'Anyone who follows a broken or mistyped link gets a blank page, with no way back into your app.'
+        : 'Broken links fall back to the framework\'s bare default 404, which looks like your site is down.',
+    fix: (s, ctx) =>
+      ({
+        next: 'Add `app/not-found.tsx` with your header and a link home.',
+        sveltekit: 'Add `src/routes/+error.svelte`.',
+        nuxt: 'Add `error.vue` at the project root.',
+        astro: 'Add `src/pages/404.astro`.',
+        remix: 'Add a splat route `app/routes/$.tsx` that renders a not-found page.',
+      })[ctx.kind] ?? 'Add a catch-all route last in your router, e.g. `<Route path="*" element={<NotFound />} />`, with a link back home.',
+  },
+  {
+    id: 'error-page',
+    title: 'Error page',
+    missing: 'No error page',
+    applies: (s, ctx) => ctx.kind === 'next' || (ctx.kind === 'spa' && ctx.deps.has('react')),
+    priority: (s, ctx) => (ctx.kind === 'spa' ? 'must' : 'should'),
+    check(files, ctx) {
+      if (ctx.kind === 'next') return exists(ctx, /(^|\/)(src\/)?app\/(?:.*\/)?(global-)?error\.[jt]sx?$|(^|\/)(src\/)?pages\/(_error|500)\.[jt]sx?$/);
+      return !!locate(files, /ErrorBoundary|componentDidCatch|errorElement\s*[:=]|errorComponent/);
+    },
+    why: (s, ctx) =>
+      ctx.kind === 'spa'
+        ? 'If any component throws, React unmounts the whole app and every visitor sees a white screen.'
+        : 'An unexpected error shows Next.js\'s generic "Application error" screen instead of a friendly message and a way to retry.',
+    fix: (s, ctx) =>
+      ctx.kind === 'next'
+        ? 'Add `app/error.tsx` (and `app/global-error.tsx`) with a message and a "Try again" button that calls `reset()`.'
+        : 'Wrap your app in an error boundary, e.g. `react-error-boundary`: `<ErrorBoundary fallback={<CrashPage />}><App /></ErrorBoundary>`.',
+  },
+  {
+    id: 'privacy-policy',
+    title: 'Privacy policy',
+    missing: 'No privacy policy',
+    applies: (s, ctx) => ctx.app && (s.accounts || s.payments || s.analytics),
+    priority: () => 'must',
+    check: (files, ctx) =>
+      exists(ctx, /privacy/i) || !!locate(files, /["'`]\/(?:legal\/)?privacy(?:[-_]policy)?["'`/#?]|href\s*=\s*\{?["'`]https?:[^"'`]*privacy/i, PAGES),
+    why: (s) => {
+      const what = [s.accounts && 'user accounts', s.payments && 'payments', s.analytics && 'analytics'].filter(Boolean).join(', ');
+      return `Your app has ${what}, so it collects personal data. Privacy laws (GDPR, CCPA) require a privacy policy, and Google sign-in, Stripe and the app stores ask for its URL.`;
+    },
+    fix: () =>
+      'Add a `/privacy` page covering what you collect, why, which services process it (e.g. Supabase, Stripe) and how users can get their data deleted. Link it in the footer and on the sign-up form.',
+  },
+  {
+    id: 'terms-of-service',
+    title: 'Terms of service',
+    missing: 'No terms of service',
+    applies: (s, ctx) => ctx.app && s.payments,
+    priority: () => 'must',
+    check: (files, ctx) =>
+      exists(ctx, /(^|\/|[-_])(terms|tos)([-_.\/]|$)/i) || !!locate(files, /["'`]\/(?:legal\/)?(?:terms|tos)(?:[-_]of[-_](?:service|use))?["'`/#?]|href\s*=\s*\{?["'`]https?:[^"'`]*terms/i, PAGES),
+    why: () => 'You take payments, so you need terms covering refunds, cancellations and acceptable use. Stripe expects them on your site before it activates live payments.',
+    fix: () => 'Add a `/terms` page with your refund and cancellation policy, and link it at checkout and in the footer.',
+  },
+  {
+    id: 'password-reset',
+    title: 'Password reset',
+    missing: 'No way to reset a forgotten password',
+    applies: (s) => s.passwordAuth && !s.hostedAuthUi,
+    priority: () => 'must',
+    check: (files) => !!locate(files, /resetPasswordForEmail|sendPasswordResetEmail|forgot[-_ ]?password|reset[-_ ]?password|ForgotPassword|ResetPassword|updateUser\(\s*\{\s*password/i),
+    why: () => "Users sign in with a password, but there's no way to reset it. Anyone who forgets theirs is locked out for good.",
+    fix: () =>
+      'Add a "Forgot password?" link. Supabase: `supabase.auth.resetPasswordForEmail(email, { redirectTo })` plus a page that calls `supabase.auth.updateUser({ password })`. Firebase: `sendPasswordResetEmail(auth, email)`.',
+  },
+  {
+    id: 'account-deletion',
+    title: 'Account deletion',
+    missing: 'No way for users to delete their account',
+    applies: (s) => s.accounts && !s.hostedAuthUi,
+    priority: () => 'should',
+    check: (files) => !!locate(files, /deleteUser|delete[-_ ]?account|deleteMyAccount|close[-_ ]?account|delete_user|user\.delete\(\)/i),
+    why: () => 'GDPR gives users the right to have their data deleted, and Apple rejects apps with sign-up but no in-app account deletion.',
+    fix: () => 'Add a "Delete account" button that calls a server function: confirm who the user is, delete their rows, then `supabase.auth.admin.deleteUser(user.id)` (or your auth provider\'s equivalent).',
+  },
+  {
+    id: 'ai-rate-limit',
+    title: 'Rate limits on AI calls',
+    missing: 'No rate limit on paid AI calls',
+    applies: (s, ctx, files) => !!aiServerCall(files),
+    priority: () => 'must',
+    check: (files, ctx) => [...ctx.deps].some((d) => RATE_LIMIT.test(d)) || !!locate(files, RATE_LIMIT),
+    locate: (files) => aiServerCall(files),
+    why: () => 'Your server calls a paid AI API with nothing limiting how often. One script hitting that endpoint in a loop can run up a bill of thousands overnight.',
+    fix: () =>
+      'Limit requests per user or IP (e.g. `@upstash/ratelimit`, or a daily quota per user in your database), and set a monthly spending cap in your AI provider\'s dashboard.',
+  },
+  {
+    id: 'default-branding',
+    title: 'Your own title, description and favicon',
+    missing: 'Template title, description or favicon still in place',
+    applies: (s, ctx, files) => ctx.app && files.some((f) => HEAD_FILES.test(f.path)),
+    priority: () => 'must',
+    check: (files) => !boilerplate(files).length,
+    locate: (files) => boilerplate(files)[0],
+    why: (s, ctx, files) =>
+      `Browser tabs and shared links still show ${[...new Set(boilerplate(files).map((b) => b.label))].join(', ')}. It's the first thing people see when you share your link.`,
+    fix: (s, ctx, files) => `Set your own \`<title>\`, meta description, \`og:image\` and favicon in \`${boilerplate(files)[0]?.file}\`.`,
+  },
+  {
+    id: 'social-preview',
+    title: 'Social preview image',
+    missing: 'No social preview image',
+    applies: (s, ctx) => ctx.app,
+    priority: () => 'should',
+    check: (files, ctx) =>
+      exists(ctx, /(^|\/)(opengraph|twitter)-image\.\w+$/) || !!locate(files, /og:image|twitter:image|openGraph\s*:\s*\{[\s\S]{0,800}?images/, HEAD_FILES),
+    why: () => 'Without a preview image, links to your app on X, LinkedIn, Slack and iMessage show up as a plain text box.',
+    fix: (s, ctx) =>
+      ctx.kind === 'next'
+        ? 'Add a 1200×630 `app/opengraph-image.png`.'
+        : 'Add a 1200×630 image and `<meta property="og:image" content="https://yourdomain.com/og.png">` to your `<head>`.',
+  },
+  {
+    id: 'robots-sitemap',
+    title: 'robots.txt and sitemap',
+    missing: 'No robots.txt or sitemap',
+    applies: (s, ctx) => ctx.app,
+    priority: () => 'should',
+    check: (files, ctx) =>
+      exists(ctx, /(^|\/)robots\.txt$|(^|\/)(src\/)?app\/robots\.[jt]s$/) &&
+      (exists(ctx, /sitemap[^/]*\.xml$|(^|\/)(src\/)?app\/sitemap\.[jt]s$/) || [...ctx.deps].some((d) => /sitemap/.test(d))),
+    why: () => "Search engines find and index your pages faster with a robots.txt and sitemap. Without them you're harder to find on Google.",
+    fix: (s, ctx) =>
+      ctx.kind === 'next' ? 'Add `app/robots.ts` and `app/sitemap.ts` (Next.js generates the files from them).' : 'Add `public/robots.txt` and a `public/sitemap.xml` listing your public pages.',
+  },
+  {
+    id: 'error-monitoring',
+    title: 'Error monitoring',
+    missing: 'No error monitoring',
+    applies: (s, ctx) => ctx.app && (s.accounts || s.payments),
+    priority: () => 'should',
+    check: (files, ctx) => [...ctx.deps].some((d) => /^@sentry\/|logrocket|^@bugsnag\/|^rollbar$|^@highlight-run\/|^@datadog\/browser|^posthog-(js|node)$|^@axiomhq\/|^@logtail\//.test(d)),
+    why: () => "When something breaks for a user, you'll only hear about it if they bother to tell you, and most just leave.",
+    fix: (s, ctx) => `Add Sentry (free tier): \`npx @sentry/wizard@latest -i ${ctx.kind === 'next' ? 'nextjs' : 'react'}\`, or PostHog's error tracking.`,
+  },
+];
+
+const boilerplateCache = new WeakMap();
+function boilerplate(files) {
+  if (!boilerplateCache.has(files)) {
+    const hits = [];
+    for (const f of files) {
+      if (!HEAD_FILES.test(f.path)) continue;
+      for (const b of BOILERPLATE) {
+        const m = b.re.exec(f.content);
+        if (m) hits.push({ file: f.path, line: lineAt(f.content, m.index), label: b.label });
+      }
+    }
+    boilerplateCache.set(files, hits);
+  }
+  return boilerplateCache.get(files);
+}
+
+const aiCache = new WeakMap();
+function aiServerCall(files) {
+  if (!aiCache.has(files)) {
+    const server = files.filter((f) => isServerEndpoint(f) || /(^|\/)(server|api|functions|lib\/server)\//.test(f.path));
+    aiCache.set(files, locate(server, AI_CALL));
+  }
+  return aiCache.get(files);
+}
+
+/**
+ * @returns {{id: string, title: string, missing: string, priority: 'must'|'should', ok: boolean, why: string, fix: string, file?: string, line?: number}[]}
+ */
+export function runChecklist(files, ctx, skip = new Set()) {
+  if (!ctx.app) return [];
+  const s = signals(files, ctx);
+  const items = [];
+  for (const c of CHECKS) {
+    if (skip.has(c.id) || !c.applies(s, ctx, files)) continue;
+    const ok = c.check(files, ctx);
+    const item = { id: c.id, title: c.title, missing: c.missing, priority: c.priority(s, ctx), ok };
+    if (!ok) Object.assign(item, { why: c.why(s, ctx, files), fix: c.fix(s, ctx, files) }, c.locate?.(files) ?? {});
+    items.push(item);
+  }
+  return items.sort((a, b) => a.ok - b.ok || (a.priority === 'must' ? 0 : 1) - (b.priority === 'must' ? 0 : 1));
+}

package/src/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { scan } from './scanner.js';
+import { DEFAULT_MODEL, judgeFindings } from './ai-judge.js';
+import { toJson, toMarkdown, toText } from './report.js';
+import { SEVERITIES, atLeast } from './util.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const { version } = JSON.parse(fs.readFileSync(path.join(here, '..', 'package.json'), 'utf8'));
+
+const HELP = `ShipWarden ${version} · security checks for apps built with Lovable, Bolt, Cursor, v0 & co.
+
+Usage: shipwarden [path] [options]
+
+Options:
+  --format <text|json|markdown>  Output format (default: text)
+  --fail-on <severity|none>      Exit 1 if any finding is at least this severe (default: critical)
+  --ignore <glob>                Skip matching files (repeatable; also reads .shipwardenignore)
+  --no-checklist                 Skip the launch checklist (404 page, privacy policy, ...)
+  --skip-check <id>              Turn off one checklist item (repeatable; or add check:<id> to .shipwardenignore)
+  --ai                           Ask Claude to double-check uncertain findings (needs ANTHROPIC_API_KEY)
+  --model <id>                   Claude model for --ai (default: ${DEFAULT_MODEL})
+  --no-color                     Disable colors
+  -v, --version                  Print version
+  -h, --help                     Show this help
+
+Severities: ${SEVERITIES.join(', ')}
+`;
+
+function parseArgs(argv) {
+  const opts = { target: '.', format: 'text', failOn: 'critical', ignore: [], skipChecks: [], checklist: true, ai: false, model: DEFAULT_MODEL, color: process.stdout.isTTY && !process.env.NO_COLOR };
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    const value = () => {
+      const v = argv[++i];
+      if (v === undefined) throw new Error(`${arg} needs a value`);
+      return v;
+    };
+    if (arg === '-h' || arg === '--help') opts.help = true;
+    else if (arg === '-v' || arg === '--version') opts.version = true;
+    else if (arg === '--format') opts.format = value();
+    else if (arg === '--json') opts.format = 'json';
+    else if (arg === '--fail-on') opts.failOn = value();
+    else if (arg === '--ignore') opts.ignore.push(value());
+    else if (arg === '--ai') opts.ai = true;
+    else if (arg === '--no-checklist') opts.checklist = false;
+    else if (arg === '--skip-check') opts.skipChecks.push(value());
+    else if (arg === '--model') opts.model = value();
+    else if (arg === '--no-color') opts.color = false;
+    else if (arg.startsWith('-')) throw new Error(`Unknown option ${arg}`);
+    else opts.target = arg;
+  }
+  if (!['text', 'json', 'markdown'].includes(opts.format)) throw new Error(`Unknown format "${opts.format}"`);
+  if (opts.failOn !== 'none' && !SEVERITIES.includes(opts.failOn)) throw new Error(`Unknown severity "${opts.failOn}"`);
+  return opts;
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) return void process.stdout.write(HELP);
+  if (opts.version) return void console.log(version);
+
+  const root = path.resolve(opts.target);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`Not a directory: ${opts.target}`);
+  const result = await scan(root, { ignore: opts.ignore, checklist: opts.checklist, skipChecks: opts.skipChecks });
+
+  let aiNote = '';
+  let ai;
+  if (opts.ai) {
+    ai = await judgeFindings(result.findings, { model: opts.model, fileContents: result.fileContents });
+    if (ai.error) console.error(`AI review skipped: ${ai.error}.`);
+    result.findings = ai.findings;
+    if (ai.judged) aiNote = `AI reviewed ${ai.judged} uncertain finding(s), dismissed ${ai.dismissed}`;
+  }
+
+  if (opts.format === 'json') process.stdout.write(`${toJson(result, ai ? { ai: { judged: ai.judged, dismissed: ai.dismissed } } : {})}\n`);
+  else if (opts.format === 'markdown') process.stdout.write(`${toMarkdown(result, { aiNote })}\n`);
+  else process.stdout.write(toText(result, { color: opts.color, aiNote }));
+
+  if (result.findings.some((f) => atLeast(f.severity, opts.failOn))) process.exitCode = 1;
+}
+
+main().catch((error) => {
+  console.error(`shipwarden: ${error.message}`);
+  process.exitCode = 2;
+});

package/src/github.js

@@ -0,0 +1,52 @@
+const API = process.env.GITHUB_API_URL || 'https://api.github.com';
+
+async function request(token, method, url, body) {
+  const res = await fetch(url.startsWith('http') ? url : `${API}${url}`, {
+    method,
+    headers: {
+      authorization: `Bearer ${token}`,
+      accept: 'application/vnd.github+json',
+      'x-github-api-version': '2022-11-28',
+      'user-agent': 'shipwarden',
+      ...(body ? { 'content-type': 'application/json' } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    const error = new Error(`GitHub API ${method} ${url} returned ${res.status}: ${text.slice(0, 200)}`);
+    error.status = res.status;
+    throw error;
+  }
+  return { data: res.status === 204 ? null : await res.json(), link: res.headers.get('link') };
+}
+
+async function paginate(token, url) {
+  const items = [];
+  for (let next = url; next; ) {
+    const { data, link } = await request(token, 'GET', next);
+    items.push(...data);
+    next = link?.match(/<([^>]+)>;\s*rel="next"/)?.[1];
+  }
+  return items;
+}
+
+/** Paths added or modified by the pull request. */
+export async function listPullFiles({ token, owner, repo, number }) {
+  const files = await paginate(token, `/repos/${owner}/${repo}/pulls/${number}/files?per_page=100`);
+  return new Set(files.filter((f) => f.status !== 'removed').map((f) => f.filename));
+}
+
+/** Edit our previous comment in place instead of posting a new one on every push. */
+export async function upsertComment({ token, owner, repo, number, marker, body, createIfMissing }) {
+  const comments = await paginate(token, `/repos/${owner}/${repo}/issues/${number}/comments?per_page=100`);
+  const existing = comments.find((c) => c.body?.includes(marker));
+  if (existing) {
+    if (existing.body === body) return 'unchanged';
+    await request(token, 'PATCH', `/repos/${owner}/${repo}/issues/comments/${existing.id}`, { body });
+    return 'updated';
+  }
+  if (!createIfMissing) return 'skipped';
+  await request(token, 'POST', `/repos/${owner}/${repo}/issues/${number}/comments`, { body });
+  return 'created';
+}

package/src/report.js

@@ -0,0 +1,129 @@
+import { SEVERITIES } from './util.js';
+
+export const MARKER = '<!-- shipwarden -->';
+const ICON = { critical: '🔴', high: '🟠', medium: '🟡', low: '⚪' };
+
+export function countBySeverity(findings) {
+  const counts = Object.fromEntries(SEVERITIES.map((s) => [s, 0]));
+  for (const f of findings) counts[f.severity]++;
+  return counts;
+}
+
+function summaryLine(findings) {
+  const counts = countBySeverity(findings);
+  return SEVERITIES.filter((s) => counts[s]).map((s) => `${counts[s]} ${s}`).join(' · ');
+}
+
+const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+const cell = (text) => text.replace(/\|/g, '\\|').replace(/\n/g, ' ');
+
+/**
+ * @param {{findings: object[], filesScanned: number, stack: string[]}} result
+ * @param {{link?: (file: string, line: number) => string, scopeNote?: string, aiNote?: string, maxItems?: number}} opts
+ */
+export function toMarkdown(result, { link, scopeNote, aiNote, maxItems = 30 } = {}) {
+  const { findings } = result;
+  const scanned = `Scanned ${plural(result.filesScanned, 'file')}${scopeNote ? ` · reporting on ${scopeNote}` : ''}${result.stack.length ? ` · ${result.stack.join(', ')}` : ''}`;
+  const footer = [`<sub>${scanned}${aiNote ? ` · ${aiNote}` : ''}. To silence a finding, put a <code>shipwarden-ignore</code> comment on the line above it.</sub>`];
+
+  if (!findings.length) return [MARKER, '### ✅ ShipWarden: no security issues found', '', ...checklistMarkdown(result.checklist), ...footer].join('\n');
+
+  const shown = findings.slice(0, maxItems);
+  const where = (f) => (link ? `[\`${f.file}:${f.line}\`](${link(f.file, f.line)})` : `\`${f.file}:${f.line}\``);
+  const out = [
+    MARKER,
+    `### 🛡️ ShipWarden found ${plural(findings.length, 'security issue')}`,
+    '',
+    `**${summaryLine(findings)}**`,
+    '',
+    '| | Issue | Where |',
+    '|---|---|---|',
+    ...shown.map((f) => `| ${ICON[f.severity]} | ${cell(f.title)} | ${where(f)} |`),
+    '',
+  ];
+  if (findings.length > shown.length) out.push(`_…and ${findings.length - shown.length} more. Run \`npx shipwarden\` locally for the full list._`, '');
+
+  for (const f of shown) {
+    out.push(
+      `<details><summary>${ICON[f.severity]} <b>${f.title.replace(/`([^`]+)`/g, '<code>$1</code>')}</b> · <code>${f.file}:${f.line}</code></summary>`,
+      '',
+      f.message,
+      '',
+      `**How to fix:** ${f.ai?.fix || f.fix}`,
+    );
+    if (f.ai) out.push('', `> 🤖 AI review (${f.ai.verdict === 'real' ? 'confirmed' : 'unsure'}): ${f.ai.reason}`);
+    out.push('', '</details>', '');
+  }
+  return [...out, ...checklistMarkdown(result.checklist), ...footer].join('\n');
+}
+
+function checklistSummary(items) {
+  const done = items.filter((i) => i.ok).length;
+  const mustMissing = items.filter((i) => !i.ok && i.priority === 'must').length;
+  return `${done} of ${items.length} done${mustMissing ? ` · ${mustMissing} must-have${mustMissing === 1 ? '' : 's'} missing` : ''}`;
+}
+
+function checklistMarkdown(items = []) {
+  if (!items.length) return [];
+  const out = [`<details${items.some((i) => !i.ok && i.priority === 'must') ? ' open' : ''}><summary>📋 <b>Launch checklist</b>: ${checklistSummary(items)}</summary>`, ''];
+  for (const i of items.filter((i) => !i.ok)) {
+    const where = i.file ? ` (\`${i.file}:${i.line}\`)` : '';
+    out.push(`- ${i.priority === 'must' ? '❌' : '⚠️'} **${i.missing}**${i.priority === 'must' ? ' · must have' : ''}${where}: ${i.why} **Fix:** ${i.fix}`);
+  }
+  const done = items.filter((i) => i.ok);
+  if (done.length) out.push(`- ✅ ${done.map((i) => i.title).join(', ')}`);
+  return [...out, '', '</details>', ''];
+}
+
+const escapeData = (s) => s.replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+const escapeProp = (s) => escapeData(s).replace(/:/g, '%3A').replace(/,/g, '%2C');
+const LEVEL = { critical: 'error', high: 'error', medium: 'warning', low: 'notice' };
+
+/** GitHub workflow commands that show each finding inline on the PR diff. */
+export function toAnnotations(findings) {
+  return findings.map(
+    (f) => `::${LEVEL[f.severity]} file=${escapeProp(f.file)},line=${f.line},title=${escapeProp(`ShipWarden: ${f.title.replace(/`/g, '')}`)}::${escapeData(`${f.message}\n\nFix: ${f.ai?.fix || f.fix}`)}`,
+  );
+}
+
+const ANSI = { critical: '\x1b[41;97;1m', high: '\x1b[43;30;1m', medium: '\x1b[33;1m', low: '\x1b[37m', dim: '\x1b[2m', bold: '\x1b[1m', green: '\x1b[32;1m', reset: '\x1b[0m' };
+
+export function toText(result, { color = false, aiNote } = {}) {
+  const c = (code, s) => (color ? `${ANSI[code]}${s}${ANSI.reset}` : s);
+  const strip = (s) => s.replace(/`/g, '');
+  const head = `ShipWarden · scanned ${plural(result.filesScanned, 'file')}${result.stack.length ? ` (${result.stack.join(', ')})` : ''} in ${result.durationMs}ms${aiNote ? ` · ${aiNote}` : ''}`;
+  const lines = [c('dim', head), ''];
+  if (!result.findings.length) lines.push(c('green', '✔ No security issues found.'), '');
+  for (const f of result.findings) {
+    lines.push(
+      `${c(f.severity, ` ${f.severity.toUpperCase()} `)} ${c('bold', strip(f.title))}`,
+      `  ${c('dim', `${f.file}:${f.line}`)}`,
+      `  ${strip(f.message)}`,
+      `  ${c('bold', 'Fix:')} ${strip(f.ai?.fix || f.fix)}`,
+    );
+    if (f.ai) lines.push(`  ${c('dim', `AI review (${f.ai.verdict}): ${f.ai.reason}`)}`);
+    lines.push('');
+  }
+  if (result.findings.length) lines.push(`${c('bold', `${plural(result.findings.length, 'issue')}:`)} ${summaryLine(result.findings)}`, '');
+
+  const items = result.checklist ?? [];
+  if (items.length) {
+    lines.push(c('bold', `Launch checklist · ${checklistSummary(items)}`), '');
+    for (const i of items.filter((i) => !i.ok)) {
+      lines.push(
+        ` ${i.priority === 'must' ? c('high', ' MUST HAVE ') : c('medium', 'NICE TO HAVE')} ${c('bold', i.missing)}${i.file ? c('dim', `  ${i.file}:${i.line}`) : ''}`,
+        `  ${strip(i.why)}`,
+        `  ${c('bold', 'Fix:')} ${strip(i.fix)}`,
+        '',
+      );
+    }
+    const done = items.filter((i) => i.ok);
+    if (done.length) lines.push(`${c('green', ' ✔ Done:')} ${done.map((i) => i.title).join(' · ')}`, '');
+  }
+  return `${lines.join('\n')}`;
+}
+
+export function toJson(result, extra = {}) {
+  const { fileContents, ...rest } = result;
+  return JSON.stringify({ ...rest, ...extra }, null, 2);
+}

package/src/rules/firebase.js

@@ -0,0 +1,116 @@
+import { blank, lineAt, makeFinding } from '../util.js';
+
+const WRITE_OPS = new Set(['write', 'create', 'update', 'delete']);
+const READ_OPS = new Set(['read', 'get', 'list']);
+
+function access(ops) {
+  const reads = ops.some((op) => READ_OPS.has(op));
+  const writes = ops.some((op) => WRITE_OPS.has(op));
+  return reads && writes ? 'read and write' : writes ? 'write to' : 'read';
+}
+const ALLOW = /\ballow\s+(?<ops>[a-z]+(?:\s*,\s*[a-z]+)*)\s*(?<cond>:\s*if\b[^;]*)?;/g;
+const MATCH_TOKEN = /match\s+((?:[^\s{]|\{[^}]*\})+)\s*\{|\{|\}/g;
+
+function stripComments(rules) {
+  return rules.replace(/\/\*[\s\S]*?\*\//g, blank).replace(/\/\/[^\n]*/g, blank);
+}
+
+/** The `match` paths enclosing a position, outermost first. */
+function matchPathsAt(rules, index) {
+  const stack = [];
+  for (const m of rules.matchAll(MATCH_TOKEN)) {
+    if (m.index >= index) break;
+    if (m[1]) stack.push(m[1]);
+    else if (m[0] === '{') stack.push(null);
+    else stack.pop();
+  }
+  return stack.filter(Boolean);
+}
+
+export const openRules = {
+  id: 'firebase-open-rules',
+  title: 'Firebase security rules are open',
+  severity: 'critical',
+  check(file) {
+    if (!/(^|\/)(firestore|storage)\.rules$|\.rules$/.test(file.path)) return [];
+    const rules = stripComments(file.content);
+    const service = /service\s+firebase\.storage/.test(rules) ? 'Storage bucket' : 'database';
+    const findings = [];
+    for (const m of rules.matchAll(ALLOW)) {
+      const ops = m.groups.ops.split(/\s*,\s*/);
+      const writes = ops.some((op) => WRITE_OPS.has(op));
+      const cond = (m.groups.cond ?? '').replace(/^:\s*if\s*/, '').trim();
+      const paths = matchPathsAt(rules, m.index);
+      const inner = paths.at(-1) ?? '';
+      const catchAll = /\{\w+=\*\*\}/.test(inner);
+      const topLevelCatchAll = catchAll && paths.length <= 2;
+      const line = lineAt(file.content, m.index);
+      const testMode = /request\.time\s*<\s*timestamp\.date\(\s*(\d{4})\s*,\s*(\d{1,2})\s*,\s*(\d{1,2})\s*\)/.exec(cond);
+
+      if (cond === '' || cond === 'true') {
+        if (!writes && (!catchAll || service !== 'database')) {
+          findings.push(
+            makeFinding(this, file.path, line, {
+              severity: catchAll ? 'medium' : 'low',
+              confidence: 'medium',
+              title: catchAll ? `Anyone can read every file in your ${service}` : `Anyone can read \`${inner}\``,
+              message: `These rules let anyone on the internet read ${catchAll ? `every file in your ${service}` : `\`${inner}\``} without signing in. Fine for truly public data (like product images), a leak for anything personal.`,
+              fix: 'If this is user data, require ownership: `allow read: if request.auth != null && request.auth.uid == userId;`',
+            }),
+          );
+          continue;
+        }
+        findings.push(
+          makeFinding(this, file.path, line, {
+            title: `Anyone can ${access(ops)} your ${service}`,
+            message: `\`allow ${m.groups.ops}${cond ? ': if true' : ''}\` on \`${inner || '/'}\` lets anyone on the internet ${ops.join('/')} without signing in.${writes ? ' They can wipe or rewrite your data.' : ''}`,
+            fix: 'Lock rules down per collection, e.g. `match /users/{userId} { allow read, write: if request.auth != null && request.auth.uid == userId; }`',
+          }),
+        );
+      } else if (testMode) {
+        const [, y, mo, d] = testMode;
+        findings.push(
+          makeFinding(this, file.path, line, {
+            title: `Firebase "test mode" rules are still in place`,
+            message: `Until ${y}-${mo.padStart(2, '0')}-${d.padStart(2, '0')} anyone can ${ops.join('/')} your entire ${service}. After that date every request is denied and the app stops working.`,
+            fix: 'Replace the `request.time < timestamp.date(...)` rule with real per-collection rules before launch.',
+          }),
+        );
+      } else if (topLevelCatchAll && /^request\.auth(\.uid)?\s*!=\s*null$/.test(cond)) {
+        findings.push(
+          makeFinding(this, file.path, line, {
+            severity: 'high',
+            title: `Any signed-in user can ${access(ops)} your whole ${service}`,
+            message: `This catch-all rule only checks that the caller is signed in. Anyone can create a free account in your app and then ${ops.join('/')} every other user's data.`,
+            fix: 'Replace the catch-all with per-collection rules that check ownership, e.g. `request.auth.uid == resource.data.ownerId`.',
+          }),
+        );
+      }
+    }
+    return findings;
+  },
+};
+
+export const openRealtimeDb = {
+  id: 'firebase-rtdb-open',
+  title: 'Realtime Database rules are open',
+  severity: 'critical',
+  check(file) {
+    if (!/(^|\/)database\.rules\.json$/.test(file.path)) return [];
+    const findings = [];
+    for (const m of file.content.matchAll(/"\.(read|write)"\s*:\s*(?:true|"true")/g)) {
+      const write = m[1] === 'write';
+      findings.push(
+        makeFinding(this, file.path, lineAt(file.content, m.index), {
+          severity: write ? 'critical' : 'high',
+          title: `Anyone can ${m[1]} your Realtime Database`,
+          message: `\`".${m[1]}": true\` lets anyone on the internet ${m[1]} this part of your database without signing in.`,
+          fix: 'Use `"auth != null && auth.uid === $uid"` style rules scoped to each user\'s data.',
+        }),
+      );
+    }
+    return findings;
+  },
+};
+
+export default [openRules, openRealtimeDb];

package/src/rules/index.js

@@ -0,0 +1,7 @@
+import secrets from './secrets.js';
+import supabase from './supabase.js';
+import firebase from './firebase.js';
+import web from './web.js';
+
+export const RULES = [...secrets, ...supabase, ...firebase, ...web];
+export const RULE_IDS = new Set(RULES.map((r) => r.id));