@eduardbar/drift 1.3.0 → 1.4.0

package/src/reporter.ts

@@ -1,71 +1,60 @@
-import type { FileReport, DriftReport, DriftIssue, AIOutput, AIIssue } from './types.js'
+import type {
+  FileReport,
+  DriftReport,
+  DriftIssue,
+  AIOutput,
+  AIIssue,
+  AIOutputJson,
+  DriftReportJson,
+} from './types.js'
 import { scoreToGradeText, severityIcon } from './utils.js'
 import { computeRepoQuality, computeMaintenanceRisk } from './metrics.js'
+import { OUTPUT_SCHEMA, withOutputMetadata } from './output-metadata.js'
+import {
+  AI_CODE_SMELL_BOOST,
+  AI_LIKELIHOOD_THRESHOLD,
+  AI_SIGNAL_RULES,
+  AI_SMELL_SCORE_MULTIPLIER,
+  AI_SUSPECTED_LIMIT,
+  AI_TRIGGER_LIMIT,
+  EFFORT_ORDER,
+  FIX_SUGGESTIONS,
+  RULE_EFFORT,
+  SEVERITY_ORDER,
+  type DriftIssueWithFile,
+} from './reporter-constants.js'
 
-const FIX_SUGGESTIONS: Record<string, string> = {
-  'large-file': 'Consider splitting this file into smaller modules with single responsibility',
-  'large-function': 'Extract logic into smaller functions with descriptive names',
-  'debug-leftover': 'Remove this console.log or replace with proper logging library',
-  'dead-code': 'Remove unused import to keep code clean',
-  'duplicate-function-name': 'Consolidate with existing function or rename to clarify different behavior',
-  'any-abuse': "Replace 'any' with proper type definition",
-  'catch-swallow': 'Add error handling or logging in catch block',
-  'no-return-type': 'Add explicit return type for better type safety',
-}
-
-const RULE_EFFORT: Record<string, 'low' | 'medium' | 'high'> = {
-  'debug-leftover': 'low',
-  'dead-code': 'low',
-  'no-return-type': 'low',
-  'any-abuse': 'medium',
-  'catch-swallow': 'medium',
-  'large-file': 'high',
-  'large-function': 'high',
-  'duplicate-function-name': 'high',
-}
-
-const SEVERITY_ORDER: Record<string, number> = { error: 0, warning: 1, info: 2 }
-const EFFORT_ORDER: Record<string, number> = { low: 0, medium: 1, high: 2 }
-const AI_SIGNAL_RULES = new Set([
-  'over-commented',
-  'hardcoded-config',
-  'inconsistent-error-handling',
-  'unnecessary-abstraction',
-  'naming-inconsistency',
-  'comment-contradiction',
-  'promise-style-mix',
-  'any-abuse',
-  'ai-code-smell',
-])
-
-export function buildReport(targetPath: string, files: FileReport[]): DriftReport {
-  const allIssues = files.flatMap((f) => f.issues)
+function summarizeIssues(allIssues: DriftIssue[]): DriftReport['summary'] {
   const byRule: Record<string, number> = {}
 
   for (const issue of allIssues) {
     byRule[issue.rule] = (byRule[issue.rule] ?? 0) + 1
   }
 
-  const totalScore =
-    files.length > 0
-      ? Math.round(files.reduce((sum, f) => sum + f.score, 0) / files.length)
-      : 0
+  return {
+    errors: allIssues.filter((issue) => issue.severity === 'error').length,
+    warnings: allIssues.filter((issue) => issue.severity === 'warning').length,
+    infos: allIssues.filter((issue) => issue.severity === 'info').length,
+    byRule,
+  }
+}
 
-  const sortedFiles = files.filter((f) => f.issues.length > 0).sort((a, b) => b.score - a.score)
+function calculateTotalScore(files: FileReport[]): number {
+  if (files.length === 0) return 0
+  return Math.round(files.reduce((sum, file) => sum + file.score, 0) / files.length)
+}
 
-  const baseReport: DriftReport = {
+function baseReportDefaults(summary: DriftReport['summary'], targetPath: string, files: FileReport[]): DriftReportJson {
+  const filesWithIssues = files.filter((file) => file.issues.length > 0).sort((a, b) => b.score - a.score)
+
+  const report: DriftReport = {
     scannedAt: new Date().toISOString(),
     targetPath,
-    files: sortedFiles,
-    totalIssues: allIssues.length,
-    totalScore,
+    files: filesWithIssues,
+    totalIssues: files.flatMap((file) => file.issues).length,
+    totalScore: calculateTotalScore(files),
     totalFiles: files.length,
-    summary: {
-      errors: allIssues.filter((i) => i.severity === 'error').length,
-      warnings: allIssues.filter((i) => i.severity === 'warning').length,
-      infos: allIssues.filter((i) => i.severity === 'info').length,
-      byRule,
-    },
+    summary,
     quality: {
       overall: 100,
       dimensions: {
@@ -87,6 +76,14 @@ export function buildReport(targetPath: string, files: FileReport[]): DriftRepor
     },
   }
 
+  return withOutputMetadata(report, OUTPUT_SCHEMA.report)
+}
+
+export function buildReport(targetPath: string, files: FileReport[]): DriftReportJson {
+  const allIssues = files.flatMap((f) => f.issues)
+  const summary = summarizeIssues(allIssues)
+  const baseReport = baseReportDefaults(summary, targetPath, files)
+
   baseReport.quality = computeRepoQuality(targetPath, files)
   baseReport.maintenanceRisk = computeMaintenanceRisk(baseReport)
 
@@ -158,8 +155,8 @@ export function formatMarkdown(report: DriftReport): string {
   return lines.join('\n')
 }
 
-function collectAllIssues(report: DriftReport): Array<{ file: string; issue: DriftIssue }> {
-  const all: Array<{ file: string; issue: DriftIssue }> = []
+function collectAllIssues(report: DriftReport): DriftIssueWithFile[] {
+  const all: DriftIssueWithFile[] = []
   for (const file of report.files) {
     for (const issue of file.issues) {
       all.push({ file: file.path, issue })
@@ -168,7 +165,7 @@ function collectAllIssues(report: DriftReport): Array<{ file: string; issue: Dri
   return all
 }
 
-function sortIssues(issues: Array<{ file: string; issue: DriftIssue }>): Array<{ file: string; issue: DriftIssue }> {
+function sortIssues(issues: DriftIssueWithFile[]): DriftIssueWithFile[] {
   return issues.sort((a, b) => {
     const sevDiff = SEVERITY_ORDER[a.issue.severity] - SEVERITY_ORDER[b.issue.severity]
     if (sevDiff !== 0) return sevDiff
@@ -178,7 +175,7 @@ function sortIssues(issues: Array<{ file: string; issue: DriftIssue }>): Array<{
   })
 }
 
-function buildAIIssue(item: { file: string; issue: DriftIssue }, rank: number): AIIssue {
+function buildAIIssue(item: DriftIssueWithFile, rank: number): AIIssue {
   return {
     rank,
     file: item.file,
@@ -209,12 +206,12 @@ function fileAILikelihood(fileIssues: DriftIssue[]): { score: number; triggers:
     triggerCounts.set(issue.rule, (triggerCounts.get(issue.rule) ?? 0) + 1)
   }
   const triggerTotal = [...triggerCounts.values()].reduce((sum, count) => sum + count, 0)
-  const smellBoost = fileIssues.some((issue) => issue.rule === 'ai-code-smell') ? 20 : 0
+  const smellBoost = fileIssues.some((issue) => issue.rule === 'ai-code-smell') ? AI_CODE_SMELL_BOOST : 0
   const ratioScore = Math.round((triggerTotal / Math.max(fileIssues.length, 1)) * 100)
   const score = Math.max(0, Math.min(100, ratioScore + smellBoost))
   const triggers = [...triggerCounts.entries()]
     .sort((a, b) => b[1] - a[1])
-    .slice(0, 4)
+    .slice(0, AI_TRIGGER_LIMIT)
     .map(([rule]) => rule)
   return { score, triggers }
 }
@@ -233,7 +230,7 @@ function computeAILikelihood(report: DriftReport): {
         triggers: likelihood.triggers,
       }
     })
-    .filter((entry) => entry.ai_likelihood >= 35)
+    .filter((entry) => entry.ai_likelihood >= AI_LIKELIHOOD_THRESHOLD)
     .sort((a, b) => b.ai_likelihood - a.ai_likelihood)
 
   const overall = suspected.length === 0
@@ -241,16 +238,16 @@ function computeAILikelihood(report: DriftReport): {
     : Math.round(suspected.reduce((sum, entry) => sum + entry.ai_likelihood, 0) / suspected.length)
 
   const smellCount = report.files.flatMap((file) => file.issues).filter((issue) => issue.rule === 'ai-code-smell').length
-  const smellScore = Math.min(100, smellCount * 15)
+  const smellScore = Math.min(100, smellCount * AI_SMELL_SCORE_MULTIPLIER)
 
   return {
     overall,
-    files: suspected.slice(0, 10),
+    files: suspected.slice(0, AI_SUSPECTED_LIMIT),
     smellScore,
   }
 }
 
-export function formatAIOutput(report: DriftReport): AIOutput {
+export function formatAIOutput(report: DriftReport): AIOutputJson {
   const allIssues = collectAllIssues(report)
   const sortedIssues = sortIssues(allIssues)
   const priorityOrder = sortedIssues.map((item, i) => buildAIIssue(item, i + 1))
@@ -258,7 +255,7 @@ export function formatAIOutput(report: DriftReport): AIOutput {
   const grade = scoreToGradeText(report.totalScore)
   const aiLikelihood = computeAILikelihood(report)
 
-  return {
+  const output: AIOutput = {
     summary: {
       score: report.totalScore,
       grade: grade.label.toUpperCase(),
@@ -279,4 +276,6 @@ export function formatAIOutput(report: DriftReport): AIOutput {
       recommended_action: buildRecommendedAction(priorityOrder),
     },
   }
+
+  return withOutputMetadata(output, OUTPUT_SCHEMA.ai)
 }

package/src/review.ts

@@ -6,7 +6,7 @@ import { cleanupTempDir, extractFilesAtRef } from './git.js'
 import { computeDiff } from './diff.js'
 import type { DriftDiff } from './types.js'
 
-export interface DriftReview {
+interface DriftReview {
   baseRef: string
   scannedAt: string
   totalDelta: number
@@ -18,10 +18,12 @@ export interface DriftReview {
   diff: DriftDiff
 }
 
+const REVIEW_TOP_FILES_LIMIT = 8
+
 export function formatReviewMarkdown(review: DriftReview): string {
   const trendIcon = review.status === 'regressed' ? '⚠️' : review.status === 'improved' ? '✅' : 'ℹ️'
   const topFiles = review.diff.files
-    .slice(0, 8)
+    .slice(0, REVIEW_TOP_FILES_LIMIT)
     .map((file) => {
       const sign = file.scoreDelta > 0 ? '+' : ''
       return `- \`${file.path}\`: ${file.scoreBefore} -> ${file.scoreAfter} (${sign}${file.scoreDelta}), +${file.newIssues.length} new / -${file.resolvedIssues.length} resolved`

package/src/rules/phase3-configurable.ts

@@ -23,12 +23,14 @@ const HTTP_IMPORT_PATTERNS = [
 
 function isControllerFile(filePath: string): boolean {
   const normalized = filePath.replace(/\\/g, '/').toLowerCase()
-  return normalized.includes('/controller/') || normalized.includes('/controllers/') || normalized.endsWith('controller.ts') || normalized.endsWith('controller.js')
+  const segments = normalized.split('/')
+  return segments.includes('controller') || segments.includes('controllers') || normalized.endsWith('controller.ts') || normalized.endsWith('controller.js')
 }
 
 function isServiceFile(filePath: string): boolean {
   const normalized = filePath.replace(/\\/g, '/').toLowerCase()
-  return normalized.includes('/service/') || normalized.includes('/services/') || normalized.endsWith('service.ts') || normalized.endsWith('service.js')
+  const segments = normalized.split('/')
+  return segments.includes('service') || segments.includes('services') || normalized.endsWith('service.ts') || normalized.endsWith('service.js')
 }
 
 function createIssue(rule: string, message: string, line: number, snippet: string): DriftIssue {
@@ -100,33 +102,44 @@ export function detectMaxFunctionLines(file: SourceFile, config?: DriftConfig):
 
   const issues: DriftIssue[] = []
 
+  collectFunctionLineIssues(file, maxLines, issues)
+  collectMethodLineIssues(file, maxLines, issues)
+
+  return issues
+}
+
+function countBodyLines(
+  body: ReturnType<import('ts-morph').FunctionDeclaration['getBody']> | ReturnType<import('ts-morph').MethodDeclaration['getBody']>,
+): number {
+  if (!body) return 0
+  return body.getEndLineNumber() - body.getStartLineNumber() - 1
+}
+
+function collectFunctionLineIssues(file: SourceFile, maxLines: number, issues: DriftIssue[]): void {
   for (const fn of file.getFunctions()) {
-    const body = fn.getBody()
-    if (!body) continue
-    const lines = body.getEndLineNumber() - body.getStartLineNumber() - 1
-    if (lines > maxLines) {
-      issues.push(createIssue(
-        'max-function-lines',
-        `Function '${fn.getName() ?? '(anonymous)'}' has ${lines} lines (max: ${maxLines}).`,
-        fn.getStartLineNumber(),
-        fn.getName() ?? '(anonymous)',
-      ))
-    }
+    const lines = countBodyLines(fn.getBody())
+    if (lines <= maxLines) continue
+
+    const functionName = fn.getName() ?? '(anonymous)'
+    issues.push(createIssue(
+      'max-function-lines',
+      `Function '${functionName}' has ${lines} lines (max: ${maxLines}).`,
+      fn.getStartLineNumber(),
+      functionName,
+    ))
   }
+}
 
+function collectMethodLineIssues(file: SourceFile, maxLines: number, issues: DriftIssue[]): void {
   for (const method of file.getDescendantsOfKind(SyntaxKind.MethodDeclaration)) {
-    const body = method.getBody()
-    if (!body) continue
-    const lines = body.getEndLineNumber() - body.getStartLineNumber() - 1
-    if (lines > maxLines) {
-      issues.push(createIssue(
-        'max-function-lines',
-        `Method '${method.getName()}' has ${lines} lines (max: ${maxLines}).`,
-        method.getStartLineNumber(),
-        method.getName(),
-      ))
-    }
+    const lines = countBodyLines(method.getBody())
+    if (lines <= maxLines) continue
+
+    issues.push(createIssue(
+      'max-function-lines',
+      `Method '${method.getName()}' has ${lines} lines (max: ${maxLines}).`,
+      method.getStartLineNumber(),
+      method.getName(),
+    ))
   }
-
-  return issues
 }

package/src/saas/constants.ts

@@ -0,0 +1,56 @@
+import type { SaasOperation, SaasPlan, SaasPolicy, SaasRole } from './types.js'
+
+export const STORE_VERSION = 3
+export const ACTIVE_WINDOW_DAYS = 30
+export const DEFAULT_ORGANIZATION_ID = 'default-org'
+const HOURS_PER_DAY = 24
+const MINUTES_PER_HOUR = 60
+const SECONDS_PER_MINUTE = 60
+const MILLISECONDS_PER_SECOND = 1000
+const RANDOM_ID_RADIX = 16
+const RANDOM_ID_START = 2
+const RANDOM_ID_END = 10
+
+export const DASHBOARD_REPO_LIMIT = 15
+export const DASHBOARD_BAR_UNIT = 8
+export const DASHBOARD_BAR_MIN_WIDTH = 8
+
+export const VALID_ROLES: SaasRole[] = ['owner', 'member', 'viewer']
+export const VALID_PLANS: SaasPlan[] = ['free', 'sponsor', 'team', 'business']
+
+export const ROLE_PRIORITY: Record<SaasRole, number> = {
+  viewer: 1,
+  member: 2,
+  owner: 3,
+}
+
+export const REQUIRED_ROLE_BY_OPERATION: Record<SaasOperation, SaasRole> = {
+  'snapshot:write': 'member',
+  'snapshot:read': 'viewer',
+  'summary:read': 'viewer',
+  'billing:write': 'owner',
+  'billing:read': 'viewer',
+}
+
+export const DEFAULT_SAAS_POLICY: SaasPolicy = {
+  freeUserThreshold: 7500,
+  maxRunsPerWorkspacePerMonth: 500,
+  maxReposPerWorkspace: 20,
+  retentionDays: 90,
+  strictActorEnforcement: false,
+  maxWorkspacesPerOrganizationByPlan: {
+    free: 20,
+    sponsor: 50,
+    team: 200,
+    business: 1000,
+  },
+}
+
+export function daysAgo(days: number): number {
+  const now = Date.now()
+  return now - days * HOURS_PER_DAY * MINUTES_PER_HOUR * SECONDS_PER_MINUTE * MILLISECONDS_PER_SECOND
+}
+
+export function createRandomId(prefix: string): string {
+  return `${prefix}-${Math.random().toString(RANDOM_ID_RADIX).slice(RANDOM_ID_START, RANDOM_ID_END)}`
+}

package/src/saas/dashboard.ts

@@ -0,0 +1,172 @@
+import { resolve } from 'node:path'
+import type { SaasPolicyOverrides, SaasQueryOptions, SaasSnapshot, SaasSummary } from './types.js'
+import { DASHBOARD_BAR_MIN_WIDTH, DASHBOARD_BAR_UNIT, DASHBOARD_REPO_LIMIT } from './constants.js'
+import { assertPermissionInStore, defaultSaasStorePath, loadStoreInternal, saveStore } from './store.js'
+import {
+  DEFAULT_ORGANIZATION_ID,
+  computeRunsPerMonth,
+  computeUsersRegistered,
+  escapeHtml,
+  isRepoActive,
+  isWorkspaceActive,
+  matchesRepoScope,
+  matchesTenantScope,
+  matchesWorkspaceScope,
+} from './helpers.js'
+
+function assertSummaryReadPermission(store: ReturnType<typeof loadStoreInternal>, options?: SaasQueryOptions): void {
+  const shouldEnforceActorForScope = store.policy.strictActorEnforcement && Boolean(options?.organizationId || options?.workspaceId)
+  if (!options?.actorUserId && !shouldEnforceActorForScope) return
+
+  const organizationId = options?.organizationId ?? DEFAULT_ORGANIZATION_ID
+  assertPermissionInStore(store, {
+    operation: 'summary:read',
+    organizationId,
+    workspaceId: options?.workspaceId,
+    actorUserId: options?.actorUserId,
+  })
+}
+
+function buildWorkspaceStats(store: ReturnType<typeof loadStoreInternal>): Array<{
+  organizationId: string
+  id: string
+  runs: number
+  avgScore: number
+  lastRun: string
+}> {
+  return Object.values(store.workspaces)
+    .map((workspace) => {
+      const snapshots = store.snapshots.filter((snapshot) => snapshot.organizationId === workspace.organizationId && snapshot.workspaceId === workspace.id)
+      const runs = snapshots.length
+      const avgScore = runs === 0 ? 0 : Math.round(snapshots.reduce((sum, snapshot) => sum + snapshot.totalScore, 0) / runs)
+      const lastRun = snapshots.sort((a, b) => b.createdAt.localeCompare(a.createdAt))[0]?.createdAt ?? 'n/a'
+      return {
+        organizationId: workspace.organizationId,
+        id: workspace.id,
+        runs,
+        avgScore,
+        lastRun,
+      }
+    })
+    .sort((a, b) => b.avgScore - a.avgScore)
+}
+
+function buildRepoStats(store: ReturnType<typeof loadStoreInternal>): Array<{ workspaceId: string; name: string; runs: number; avgScore: number }> {
+  return Object.values(store.repos)
+    .map((repo) => {
+      const snapshots = store.snapshots.filter((snapshot) => snapshot.repoId === repo.id)
+      const runs = snapshots.length
+      const avgScore = runs === 0 ? 0 : Math.round(snapshots.reduce((sum, snapshot) => sum + snapshot.totalScore, 0) / runs)
+      return {
+        workspaceId: repo.workspaceId,
+        name: repo.name,
+        runs,
+        avgScore,
+      }
+    })
+    .sort((a, b) => b.avgScore - a.avgScore)
+    .slice(0, DASHBOARD_REPO_LIMIT)
+}
+
+function buildRunsRows(summary: SaasSummary): string {
+  return Object.entries(summary.runsPerMonth)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([month, count]) => {
+      const width = Math.max(DASHBOARD_BAR_MIN_WIDTH, count * DASHBOARD_BAR_UNIT)
+      return `<tr><td>${escapeHtml(month)}</td><td>${count}</td><td><div class="bar" style="width:${width}px"></div></td></tr>`
+    })
+    .join('')
+}
+
+function buildWorkspaceRows(workspaceStats: Array<{ organizationId: string; id: string; runs: number; avgScore: number; lastRun: string }>): string {
+  return workspaceStats
+    .map((workspace) => `<tr><td>${escapeHtml(workspace.organizationId)}</td><td>${escapeHtml(workspace.id)}</td><td>${workspace.runs}</td><td>${workspace.avgScore}</td><td>${escapeHtml(workspace.lastRun)}</td></tr>`)
+    .join('')
+}
+
+function buildRepoRows(repoStats: Array<{ workspaceId: string; name: string; runs: number; avgScore: number }>): string {
+  return repoStats
+    .map((repo) => `<tr><td>${escapeHtml(repo.workspaceId)}</td><td>${escapeHtml(repo.name)}</td><td>${repo.runs}</td><td>${repo.avgScore}</td></tr>`)
+    .join('')
+}
+
+function renderDashboardHtmlDocument(input: {
+  storeFile: string
+  summary: SaasSummary
+  runsRows: string
+  workspaceRows: string
+  repoRows: string
+}): string {
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" /><title>drift cloud dashboard</title><style>:root { color-scheme: light; } body { margin: 0; font-family: "Segoe UI", Arial, sans-serif; background: #f4f7fb; color: #0f172a; } main { max-width: 980px; margin: 0 auto; padding: 24px; } h1 { margin: 0 0 6px; } p.meta { margin: 0 0 20px; color: #475569; } .cards { display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 12px; margin-bottom: 18px; } .card { background: #ffffff; border-radius: 10px; padding: 14px; border: 1px solid #dbe3ef; } .card .label { font-size: 12px; color: #64748b; text-transform: uppercase; letter-spacing: 0.08em; } .card .value { font-size: 26px; font-weight: 700; margin-top: 4px; } table { width: 100%; border-collapse: collapse; margin-top: 10px; background: #ffffff; border: 1px solid #dbe3ef; border-radius: 10px; overflow: hidden; } th, td { padding: 10px; border-bottom: 1px solid #e2e8f0; text-align: left; font-size: 14px; } th { background: #eef2f9; } .section { margin-top: 18px; } .bar { height: 10px; background: linear-gradient(90deg, #0ea5e9, #22c55e); border-radius: 999px; } .pill { display: inline-block; border-radius: 999px; padding: 4px 10px; font-size: 12px; font-weight: 600; } .pill.free { background: #dcfce7; color: #166534; } .pill.paid { background: #fee2e2; color: #991b1b; }</style></head><body><main><h1>drift cloud dashboard</h1><p class="meta">Store: ${escapeHtml(input.storeFile)}</p><div class="cards"><div class="card"><div class="label">Plan Phase</div><div class="value"><span class="pill ${input.summary.phase}">${input.summary.phase.toUpperCase()}</span></div></div><div class="card"><div class="label">Users</div><div class="value">${input.summary.usersRegistered}</div></div><div class="card"><div class="label">Active Workspaces</div><div class="value">${input.summary.workspacesActive}</div></div><div class="card"><div class="label">Active Repos</div><div class="value">${input.summary.reposActive}</div></div><div class="card"><div class="label">Snapshots</div><div class="value">${input.summary.totalSnapshots}</div></div><div class="card"><div class="label">Free Seats Left</div><div class="value">${input.summary.freeUsersRemaining}</div></div></div><section class="section"><h2>Runs Per Month</h2><table><thead><tr><th>Month</th><th>Runs</th><th>Trend</th></tr></thead><tbody>${input.runsRows || '<tr><td colspan="3">No runs yet</td></tr>'}</tbody></table></section><section class="section"><h2>Workspace Hotspots</h2><table><thead><tr><th>Organization</th><th>Workspace</th><th>Runs</th><th>Avg Score</th><th>Last Run</th></tr></thead><tbody>${input.workspaceRows || '<tr><td colspan="5">No workspace data</td></tr>'}</tbody></table></section><section class="section"><h2>Repo Hotspots</h2><table><thead><tr><th>Workspace</th><th>Repo</th><th>Runs</th><th>Avg Score</th></tr></thead><tbody>${input.repoRows || '<tr><td colspan="4">No repo data</td></tr>'}</tbody></table></section></main></body></html>`
+}
+
+export function listSaasSnapshots(options?: SaasQueryOptions): SaasSnapshot[] {
+  const storeFile = resolve(options?.storeFile ?? defaultSaasStorePath())
+  const store = loadStoreInternal(storeFile, options?.policy)
+
+  const shouldEnforceActorForScope = store.policy.strictActorEnforcement && Boolean(options?.organizationId || options?.workspaceId)
+  if (options?.actorUserId || shouldEnforceActorForScope) {
+    const organizationId = options?.organizationId ?? DEFAULT_ORGANIZATION_ID
+    assertPermissionInStore(store, {
+      operation: 'snapshot:read',
+      organizationId,
+      workspaceId: options?.workspaceId,
+      actorUserId: options?.actorUserId,
+    })
+  }
+
+  saveStore(storeFile, store)
+  return store.snapshots
+    .filter((snapshot) => matchesTenantScope(snapshot, options))
+    .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+}
+
+export function getSaasSummary(options?: SaasQueryOptions): SaasSummary {
+  const storeFile = resolve(options?.storeFile ?? defaultSaasStorePath())
+  const store = loadStoreInternal(storeFile, options?.policy)
+
+  assertSummaryReadPermission(store, options)
+  saveStore(storeFile, store)
+
+  const scopedSnapshots = store.snapshots.filter((snapshot) => matchesTenantScope(snapshot, options))
+  const scopedWorkspaces = Object.values(store.workspaces).filter((workspace) => matchesWorkspaceScope(workspace, options))
+  const scopedRepos = Object.values(store.repos).filter((repo) => matchesRepoScope(repo, options))
+
+  const usersRegistered = computeUsersRegistered(store, scopedSnapshots, options)
+  const workspacesActive = scopedWorkspaces.filter((workspace) => isWorkspaceActive(workspace)).length
+  const reposActive = scopedRepos.filter((repo) => isRepoActive(repo)).length
+  const runsPerMonth = computeRunsPerMonth(scopedSnapshots)
+  const thresholdReached = usersRegistered >= store.policy.freeUserThreshold
+
+  return {
+    policy: store.policy,
+    usersRegistered,
+    workspacesActive,
+    reposActive,
+    runsPerMonth,
+    totalSnapshots: scopedSnapshots.length,
+    phase: thresholdReached ? 'paid' : 'free',
+    thresholdReached,
+    freeUsersRemaining: Math.max(0, store.policy.freeUserThreshold - usersRegistered),
+  }
+}
+
+export function generateSaasDashboardHtml(options?: { storeFile?: string; policy?: SaasPolicyOverrides }): string {
+  const storeFile = resolve(options?.storeFile ?? defaultSaasStorePath())
+  const store = loadStoreInternal(storeFile, options?.policy)
+  const summary = getSaasSummary(options)
+
+  const workspaceStats = buildWorkspaceStats(store)
+  const repoStats = buildRepoStats(store)
+  const runsRows = buildRunsRows(summary)
+  const workspaceRows = buildWorkspaceRows(workspaceStats)
+  const repoRows = buildRepoRows(repoStats)
+
+  return renderDashboardHtmlDocument({
+    storeFile,
+    summary,
+    runsRows,
+    workspaceRows,
+    repoRows,
+  })
+}

package/src/saas/errors.ts

@@ -0,0 +1,45 @@
+import type { SaasOperation, SaasPermissionContext, SaasRole } from './types.js'
+
+export class SaasPermissionError extends Error {
+  readonly code = 'SAAS_PERMISSION_DENIED'
+  readonly operation: SaasOperation
+  readonly organizationId: string
+  readonly workspaceId?: string
+  readonly actorUserId?: string
+  readonly requiredRole: SaasRole
+  readonly actorRole?: SaasRole
+
+  constructor(context: SaasPermissionContext, requiredRole: SaasRole, actorRole?: SaasRole) {
+    const actor = context.actorUserId ?? 'unknown-actor'
+    const workspaceSuffix = context.workspaceId ? ` workspace='${context.workspaceId}'` : ''
+    const actualRole = actorRole ?? 'none'
+    super(
+      `Permission denied for operation '${context.operation}'. actor='${actor}' organization='${context.organizationId}'${workspaceSuffix} requiredRole='${requiredRole}' actualRole='${actualRole}'.`,
+    )
+    this.name = 'SaasPermissionError'
+    this.operation = context.operation
+    this.organizationId = context.organizationId
+    this.workspaceId = context.workspaceId
+    this.actorUserId = context.actorUserId
+    this.requiredRole = requiredRole
+    this.actorRole = actorRole
+  }
+}
+
+export class SaasActorRequiredError extends Error {
+  readonly code = 'SAAS_ACTOR_REQUIRED'
+  readonly operation: SaasOperation
+  readonly organizationId: string
+  readonly workspaceId?: string
+
+  constructor(context: SaasPermissionContext) {
+    const workspaceSuffix = context.workspaceId ? ` workspace='${context.workspaceId}'` : ''
+    super(
+      `Actor is required for operation '${context.operation}'. organization='${context.organizationId}'${workspaceSuffix}.`,
+    )
+    this.name = 'SaasActorRequiredError'
+    this.operation = context.operation
+    this.organizationId = context.organizationId
+    this.workspaceId = context.workspaceId
+  }
+}