@soulbatical/tetra-dev-toolkit 1.20.11 → 1.20.13

package/lib/audits/test-coverage-audit.js

@@ -0,0 +1,646 @@
+/**
+ * Test Coverage Audit — scans a Tetra project to find test coverage gaps.
+ *
+ * Discovers FeatureConfigs, routes, frontend pages, and test files,
+ * then cross-references to identify what is missing coverage.
+ */
+
+import { readFileSync, existsSync } from 'fs'
+import { join, basename } from 'path'
+import { glob } from 'glob'
+
+// ============================================================================
+// SCANNERS
+// ============================================================================
+
+/**
+ * Scan all FeatureConfig files and extract tableName + restBasePath.
+ */
+export async function scanFeatureConfigs(projectRoot) {
+  const pattern = 'backend/src/features/*/config/*.config.ts'
+  const files = await glob(pattern, { cwd: projectRoot })
+
+  const configs = []
+  for (const file of files) {
+    const fullPath = join(projectRoot, file)
+    const content = readFileSync(fullPath, 'utf-8')
+
+    const tableMatch = content.match(/tableName:\s*['"]([^'"]+)['"]/)
+    const restMatch = content.match(/restBasePath:\s*['"]([^'"]+)['"]/)
+    const parts = file.split('/')
+    const featureName = parts[3]
+
+    configs.push({
+      file,
+      featureName,
+      tableName: tableMatch?.[1] || null,
+      restBasePath: restMatch?.[1] || null,
+    })
+  }
+
+  return configs
+}
+
+/**
+ * Scan RouteManager to extract registered routes,
+ * and fall back to scanning route files for router.get/post/etc patterns.
+ */
+export async function scanRoutes(projectRoot) {
+  const routes = []
+
+  // Strategy 1: Parse RouteManager.ts for route groups
+  const routeManagerPath = join(projectRoot, 'backend/src/core/RouteManager.ts')
+  if (existsSync(routeManagerPath)) {
+    const content = readFileSync(routeManagerPath, 'utf-8')
+
+    const groupRegex = /name:\s*['"]([^'"]+)['"][\s\S]*?prefix:\s*['"]([^'"]*)['"][\s\S]*?routes:\s*\[([\s\S]*?)\]/g
+    let groupMatch
+    while ((groupMatch = groupRegex.exec(content)) !== null) {
+      const groupName = groupMatch[1]
+      const prefix = groupMatch[2]
+      const routesBlock = groupMatch[3]
+
+      const routeRegex = /path:\s*['"]([^'"]+)['"]/g
+      let routeMatch
+      while ((routeMatch = routeRegex.exec(routesBlock)) !== null) {
+        const path = routeMatch[1]
+        const fullPath = path === '/' ? prefix : `${prefix}${path}`
+        routes.push({
+          group: groupName,
+          prefix,
+          path,
+          fullPath,
+          source: 'RouteManager',
+        })
+      }
+    }
+  }
+
+  // Strategy 2: Scan individual route files for HTTP method registrations
+  const routeFilePattern = 'backend/src/features/*/routes/*.ts'
+  const routeFiles = await glob(routeFilePattern, { cwd: projectRoot })
+
+  for (const file of routeFiles) {
+    const fullPath = join(projectRoot, file)
+    const content = readFileSync(fullPath, 'utf-8')
+    const featureName = file.split('/')[3]
+    const routeType = basename(file, '.ts')
+
+    const methodRegex = /router\.(get|post|put|patch|delete)\(\s*['"]([^'"]+)['"]/g
+    let methodMatch
+    while ((methodMatch = methodRegex.exec(content)) !== null) {
+      routes.push({
+        method: methodMatch[1].toUpperCase(),
+        subPath: methodMatch[2],
+        featureName,
+        routeType,
+        file,
+        source: 'routeFile',
+      })
+    }
+  }
+
+  return routes
+}
+
+/**
+ * Scan frontend pages by finding all page.tsx files.
+ */
+export async function scanFrontendPages(projectRoot) {
+  const frontendPatterns = [
+    'frontend/src/app/**/page.tsx',
+    'frontend-user/src/app/**/page.tsx',
+    'frontend-sparkbuddy/src/app/**/page.tsx',
+  ]
+  const files = []
+  for (const pattern of frontendPatterns) {
+    const found = await glob(pattern, { cwd: projectRoot })
+    files.push(...found)
+  }
+
+  const pages = []
+  for (const file of files) {
+    let routePath = file
+      .replace('frontend/src/app', '')
+      .replace('/page.tsx', '') || '/'
+
+    // Remove route groups like (dashboard), (marketing), (editor), (superadmin)
+    routePath = routePath.replace(/\/\([^)]+\)/g, '')
+
+    if (!routePath.startsWith('/')) routePath = '/' + routePath
+    if (routePath === '') routePath = '/'
+
+    pages.push({
+      file,
+      routePath,
+    })
+  }
+
+  return pages
+}
+
+/**
+ * Scan all test files and extract what endpoints/pages they reference.
+ */
+export async function scanTestFiles(projectRoot) {
+  const patterns = [
+    'tests/e2e/**/*.test.ts',
+    'tests/**/*.test.ts',
+    'frontend/e2e/**/*.spec.ts',
+    'frontend-user/tests/**/*.spec.ts',
+    'frontend-user/tests/**/*.test.ts',
+    'frontend-sparkbuddy/tests/**/*.spec.ts',
+    'backend/tests/**/*.test.ts',
+    'frontend-user/tests/fixtures/**/*.ts',
+    'frontend/e2e/fixtures.ts',
+  ]
+
+  const allFiles = []
+  for (const pattern of patterns) {
+    const files = await glob(pattern, { cwd: projectRoot })
+    allFiles.push(...files)
+  }
+
+  const uniqueFiles = [...new Set(allFiles)]
+
+  const testFiles = []
+  for (const file of uniqueFiles) {
+    const fullPath = join(projectRoot, file)
+    if (!existsSync(fullPath)) continue
+    const content = readFileSync(fullPath, 'utf-8')
+
+    // Extract API endpoint references
+    const apiRefs = new Set()
+    const apiRegex = /['"`]\/api\/(admin|public|user|superadmin|internal)\/([^'"`\s?#]+)['"`]/g
+    let apiMatch
+    while ((apiMatch = apiRegex.exec(content)) !== null) {
+      const endpoint = `/api/${apiMatch[1]}/${apiMatch[2]}`
+      apiRefs.add(endpoint.replace(/\/\$\{[^}]+\}/g, ''))
+    }
+
+    // Extract page.goto references
+    const pageRefs = new Set()
+    const gotoRegex = /page\.goto\(\s*['"`]([^'"`$]+)['"`]/g
+    let gotoMatch
+    while ((gotoMatch = gotoRegex.exec(content)) !== null) {
+      pageRefs.add(gotoMatch[1])
+    }
+
+    // Template literal page.goto
+    const gotoTemplateRegex = /page\.goto\(\s*`([^`]+)`/g
+    let gotoTemplateMatch
+    while ((gotoTemplateMatch = gotoTemplateRegex.exec(content)) !== null) {
+      const basePath = gotoTemplateMatch[1].replace(/\$\{[^}]+\}/g, '').replace(/\/+$/, '')
+      if (basePath) pageRefs.add(basePath)
+    }
+
+    // Extract path definitions from fixture files (e.g. { path: '/nl/user' })
+    const pathDefRegex2 = /path:\s*['"]([^'"]+)['"]/g
+    let pathDefMatch2
+    while ((pathDefMatch2 = pathDefRegex2.exec(content)) !== null) {
+      pageRefs.add(pathDefMatch2[1])
+    }
+
+    // Detect auth wall tests
+    const hasAuthTests = /(?:toBe|toEqual|status)\s*\(\s*401\s*\)/.test(content) ||
+                        /expect\(.*status.*\).*401/.test(content) ||
+                        /\.status\)\.toBe\(401\)/.test(content)
+
+    // Detect CRUD tests
+    const hasCrudTests = /\.(post|put|patch|delete)\(/i.test(content) &&
+                        /expect\(/i.test(content)
+
+    // Extract describe block names
+    const describeNames = []
+    const describeRegex = /describe\(\s*['"]([^'"]+)['"]/g
+    let describeMatch
+    while ((describeMatch = describeRegex.exec(content)) !== null) {
+      describeNames.push(describeMatch[1])
+    }
+
+    testFiles.push({
+      file,
+      type: file.includes('frontend/e2e') ? 'frontend-e2e' : 'backend-e2e',
+      apiEndpoints: [...apiRefs],
+      pageRoutes: [...pageRefs],
+      hasAuthTests,
+      hasCrudTests,
+      describeNames,
+      rawContent: content,
+    })
+  }
+
+  return testFiles
+}
+
+/**
+ * Scan CI pipeline configuration.
+ */
+export function scanCIPipeline(projectRoot) {
+  const checks = {
+    ciExists: false,
+    ciFile: null,
+    hasApiTestJob: false,
+    hasFrontendTestJob: false,
+    hasPostDeploySmoke: false,
+    hasCoverageReporting: false,
+    hasSecurityScanning: false,
+  }
+
+  const ciPaths = [
+    '.github/workflows/ci.yml',
+    '.github/workflows/ci.yaml',
+    '.github/workflows/test.yml',
+    '.github/workflows/test.yaml',
+  ]
+
+  for (const ciPath of ciPaths) {
+    const fullPath = join(projectRoot, ciPath)
+    if (existsSync(fullPath)) {
+      checks.ciExists = true
+      checks.ciFile = ciPath
+
+      const content = readFileSync(fullPath, 'utf-8')
+
+      checks.hasApiTestJob = /api[_-]?test/i.test(content) || /e2e[_-]?test/i.test(content) || /vitest.*e2e/i.test(content)
+      checks.hasFrontendTestJob = /playwright/i.test(content) || /cypress/i.test(content) || /frontend.*test/i.test(content)
+      checks.hasPostDeploySmoke = /smoke/i.test(content) || /post[_-]?deploy/i.test(content)
+      checks.hasCoverageReporting = /coverage/i.test(content) || /codecov/i.test(content) || /coveralls/i.test(content)
+
+      checks.hasSecurityScanning = /security[_-]?gate/i.test(content) || /snyk/i.test(content) || /tetra-security/i.test(content) || /semgrep/i.test(content)
+
+      break
+    }
+  }
+
+  // Check for separate post-deploy workflow files
+  if (!checks.hasPostDeploySmoke) {
+    const postDeployPaths = [
+      '.github/workflows/post-deploy-tests.yml',
+      '.github/workflows/post-deploy.yml',
+      '.github/workflows/smoke-tests.yml',
+    ]
+    for (const pdPath of postDeployPaths) {
+      if (existsSync(join(projectRoot, pdPath))) {
+        checks.hasPostDeploySmoke = true
+        break
+      }
+    }
+  }
+
+  return checks
+}
+
+// ============================================================================
+// CROSS-REFERENCE
+// ============================================================================
+
+/**
+ * Cross-reference all scan results to produce a gap report.
+ */
+export function crossReference(features, routes, pages, testFiles, ciChecks) {
+  const testedEndpoints = new Set()
+  const authTestedEndpoints = new Set()
+  const testedPages = new Set()
+  const crudTestedFeatures = new Set()
+
+  for (const test of testFiles) {
+    for (const ep of test.apiEndpoints) {
+      testedEndpoints.add(ep)
+      testedEndpoints.add(ep.replace(/\/+$/, ''))
+    }
+
+    if (test.hasAuthTests) {
+      for (const ep of test.apiEndpoints) {
+        authTestedEndpoints.add(ep)
+        authTestedEndpoints.add(ep.replace(/\/+$/, ''))
+      }
+    }
+
+    for (const page of test.pageRoutes) {
+      testedPages.add(page)
+      testedPages.add(page.replace(/\/+$/, ''))
+    }
+  }
+
+  // Determine CRUD-tested features
+  for (const feature of features) {
+    if (!feature.restBasePath) continue
+    const basePath = feature.restBasePath
+    const hasTest = testFiles.some(t =>
+      t.apiEndpoints.some(ep => ep.startsWith(basePath)) && t.hasCrudTests
+    )
+    if (hasTest) {
+      crudTestedFeatures.add(feature.featureName)
+    }
+  }
+
+  // 1. Feature coverage gaps
+  const featureResults = features.map(f => {
+    const hasCrud = crudTestedFeatures.has(f.featureName)
+    // Match by restBasePath OR by feature directory name in route paths
+    // e.g. feature "videostudio" matches route "/api/admin/video-studio"
+    // Generate multiple slug variants to catch compound words
+    const featureSlug = f.featureName.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()
+    const slugVariants = new Set([
+      f.featureName,                          // videostudio
+      featureSlug,                            // videostudio (no camelCase)
+      f.featureName.replace(/studio/i, '-studio'),   // video-studio
+      f.featureName.replace(/generation/i, '-generation'), // image-generation
+      f.featureName.replace(/identity/i, '-identity'),
+      f.featureName.replace(/library/i, '-library'),
+    ].map(s => s.toLowerCase()))
+
+    const hasAuth = f.restBasePath
+      ? testFiles.some(t =>
+          t.apiEndpoints.some(ep => ep.startsWith(f.restBasePath)) && t.hasAuthTests
+        )
+      : testFiles.some(t =>
+          t.apiEndpoints.some(ep => {
+            const epLower = ep.toLowerCase()
+            return [...slugVariants].some(slug => epLower.includes(slug))
+          }) && t.hasAuthTests
+        )
+
+    const testedAspects = []
+    if (hasCrud) testedAspects.push('CRUD tested')
+    if (hasAuth) testedAspects.push('auth tested')
+
+    return {
+      featureName: f.featureName,
+      tableName: f.tableName,
+      restBasePath: f.restBasePath,
+      hasCrudTest: hasCrud,
+      hasAuthTest: hasAuth,
+      testedAspects,
+      covered: hasCrud || hasAuth,
+    }
+  })
+
+  // 2. API endpoint coverage
+  const routeManagerRoutes = routes.filter(r => r.source === 'RouteManager')
+  const endpointResults = []
+
+  for (const route of routeManagerRoutes) {
+    if (!route.fullPath || route.fullPath === '/' || route.fullPath === '/api' || route.fullPath === '/api/') continue
+
+    const isTested = testedEndpoints.has(route.fullPath) ||
+      [...testedEndpoints].some(ep => ep.startsWith(route.fullPath))
+    const isAuthTested = authTestedEndpoints.has(route.fullPath) ||
+      [...authTestedEndpoints].some(ep => ep.startsWith(route.fullPath))
+
+    const needsAuthTest = ['Admin', 'SuperAdmin', 'User'].includes(route.group)
+
+    // Also check if route is mentioned in test files (even as comment/documentation)
+    const mentionedInTests = isAuthTested || testFiles.some(t =>
+      t.rawContent && t.rawContent.includes(route.fullPath)
+    )
+
+    endpointResults.push({
+      endpoint: route.fullPath,
+      group: route.group,
+      isTested,
+      isAuthTested: isAuthTested || mentionedInTests,
+      needsAuthTest,
+      missingAuthTest: needsAuthTest && !isAuthTested && !mentionedInTests,
+    })
+  }
+
+  // 3. Frontend page coverage
+  const pageResults = pages.map(p => {
+    const isTested = testedPages.has(p.routePath) ||
+      [...testedPages].some(tp => {
+        const normalizedTest = tp.replace(/\/+$/, '')
+        const normalizedPage = p.routePath.replace(/\/+$/, '')
+        return normalizedTest === normalizedPage ||
+          normalizedPage.replace(/\/\[[^\]]+\]/g, '').startsWith(normalizedTest)
+      })
+
+    return {
+      routePath: p.routePath,
+      file: p.file,
+      isTested,
+    }
+  })
+
+  // 4. CI pipeline gaps
+  const ciGaps = []
+  if (!ciChecks.ciExists) ciGaps.push('No CI pipeline found')
+  if (ciChecks.ciExists && !ciChecks.hasApiTestJob) ciGaps.push('No API test job in CI')
+  if (ciChecks.ciExists && !ciChecks.hasFrontendTestJob) ciGaps.push('No frontend test job in CI')
+  if (ciChecks.ciExists && !ciChecks.hasPostDeploySmoke) ciGaps.push('No post-deploy smoke tests')
+  if (ciChecks.ciExists && !ciChecks.hasCoverageReporting) ciGaps.push('No coverage reporting')
+
+  // 5. Summary
+  const featuresCovered = featureResults.filter(f => f.covered).length
+  const featuresTotal = featureResults.length
+  const endpointsWithAuth = endpointResults.filter(e => e.needsAuthTest)
+  const authTested = endpointsWithAuth.filter(e => e.isAuthTested).length
+  const authTotal = endpointsWithAuth.length
+  const pagesTested = pageResults.filter(p => p.isTested).length
+  const pagesTotal = pageResults.length
+
+  const totalChecks = featuresTotal + authTotal + pagesTotal + 4
+  const totalPassed = featuresCovered + authTested + pagesTested +
+    (ciChecks.ciExists ? 1 : 0) +
+    (ciChecks.hasApiTestJob ? 1 : 0) +
+    (ciChecks.hasPostDeploySmoke ? 1 : 0) +
+    (ciChecks.hasCoverageReporting ? 1 : 0)
+
+  const coveragePercent = totalChecks > 0 ? Math.round((totalPassed / totalChecks) * 100) : 0
+  const totalGaps = totalChecks - totalPassed
+  const criticalGaps = endpointResults.filter(e => e.missingAuthTest).length
+
+  return {
+    features: featureResults,
+    endpoints: endpointResults,
+    pages: pageResults,
+    ci: ciChecks,
+    ciGaps,
+    summary: {
+      coveragePercent,
+      totalGaps,
+      criticalGaps,
+      featuresCovered,
+      featuresTotal,
+      authTested,
+      authTotal,
+      pagesTested,
+      pagesTotal,
+    },
+    testFiles: testFiles.map(t => ({ file: t.file, type: t.type })),
+  }
+}
+
+// ============================================================================
+// FORMATTERS
+// ============================================================================
+
+/**
+ * Format report as pretty terminal output.
+ */
+export function formatReport(report, chalk) {
+  const lines = []
+  const { features, endpoints, pages, ci, ciGaps, summary } = report
+
+  lines.push('')
+  lines.push(chalk.blue.bold('  Tetra Test Audit — Coverage Gaps'))
+  lines.push('')
+
+  // Features
+  if (features.length > 0) {
+    lines.push(chalk.white.bold('  Features (FeatureConfig):'))
+
+    for (const f of features) {
+      if (f.covered) {
+        const aspects = f.testedAspects.join(', ')
+        lines.push(chalk.green(`    ✓ ${f.featureName.padEnd(22)} ${aspects}`))
+      } else {
+        const missing = []
+        if (!f.hasCrudTest) missing.push('NO CRUD test')
+        if (!f.hasAuthTest) missing.push('NO auth test')
+        lines.push(chalk.red(`    ✗ ${f.featureName.padEnd(22)} ${missing.join(', ')}`))
+      }
+    }
+    lines.push('')
+  }
+
+  // API Endpoints
+  const authEndpoints = endpoints.filter(e => e.needsAuthTest)
+  if (authEndpoints.length > 0) {
+    const tested = authEndpoints.filter(e => e.isAuthTested).length
+    const total = authEndpoints.length
+    const missing = authEndpoints.filter(e => e.missingAuthTest)
+
+    lines.push(chalk.white.bold('  API Endpoints:'))
+    if (tested === total) {
+      lines.push(chalk.green(`    ✓ ${tested}/${total} protected routes have auth wall tests`))
+    } else {
+      lines.push(chalk.green(`    ✓ ${tested}/${total} protected routes have auth wall tests`))
+      lines.push(chalk.red(`    ✗ ${missing.length} endpoints missing auth tests:`))
+      for (const ep of missing) {
+        lines.push(chalk.red(`      - ${ep.endpoint}`))
+      }
+    }
+    lines.push('')
+  }
+
+  // Frontend Pages
+  if (pages.length > 0) {
+    const tested = pages.filter(p => p.isTested).length
+    const total = pages.length
+    const missing = pages.filter(p => !p.isTested)
+
+    lines.push(chalk.white.bold('  Frontend Pages:'))
+    if (tested === total) {
+      lines.push(chalk.green(`    ✓ ${tested}/${total} pages have e2e specs`))
+    } else {
+      lines.push(chalk.green(`    ✓ ${tested}/${total} pages have e2e specs`))
+      lines.push(chalk.red(`    ✗ ${missing.length} pages missing specs:`))
+      for (const p of missing) {
+        lines.push(chalk.red(`      - ${p.routePath}`))
+      }
+    }
+    lines.push('')
+  }
+
+  // CI Pipeline
+  lines.push(chalk.white.bold('  CI Pipeline:'))
+  if (ci.ciExists) {
+    lines.push(chalk.green(`    ✓ ${ci.ciFile} exists`))
+  } else {
+    lines.push(chalk.red(`    ✗ No CI pipeline found`))
+  }
+  if (ci.hasApiTestJob) {
+    lines.push(chalk.green(`    ✓ API test job exists`))
+  } else {
+    lines.push(chalk.red(`    ✗ No API test job`))
+  }
+  if (ci.hasFrontendTestJob) {
+    lines.push(chalk.green(`    ✓ Frontend test job exists`))
+  } else {
+    lines.push(chalk.red(`    ✗ No frontend test job`))
+  }
+  if (ci.hasPostDeploySmoke) {
+    lines.push(chalk.green(`    ✓ Post-deploy smoke tests`))
+  } else {
+    lines.push(chalk.red(`    ✗ No post-deploy smoke tests`))
+  }
+  if (ci.hasCoverageReporting) {
+    lines.push(chalk.green(`    ✓ Coverage reporting`))
+  } else {
+    lines.push(chalk.red(`    ✗ No coverage reporting`))
+  }
+  lines.push('')
+
+  // Summary
+  const pctColor = summary.coveragePercent >= 80 ? chalk.green : summary.coveragePercent >= 50 ? chalk.yellow : chalk.red
+  lines.push(pctColor.bold(`  Summary: ${summary.coveragePercent}% coverage | ${summary.totalGaps} gaps found`))
+  if (summary.criticalGaps > 0) {
+    lines.push(chalk.red.bold(`  ⚠  ${summary.criticalGaps} critical gaps (missing auth wall tests)`))
+  }
+  lines.push('')
+
+  return lines.join('\n')
+}
+
+/**
+ * Format report as JSON.
+ */
+export function formatReportJSON(report) {
+  return JSON.stringify(report, null, 2)
+}
+
+/**
+ * Output GitHub Actions annotations for gaps.
+ */
+export function formatCIAnnotations(report) {
+  const annotations = []
+  const { features, endpoints, pages, ciGaps } = report
+
+  for (const f of features) {
+    if (!f.covered) {
+      annotations.push(`::warning title=Missing Test::Feature "${f.featureName}" has no CRUD or auth test`)
+    }
+  }
+
+  for (const ep of endpoints) {
+    if (ep.missingAuthTest) {
+      annotations.push(`::error title=Missing Auth Test::Endpoint ${ep.endpoint} has no auth wall test`)
+    }
+  }
+
+  for (const p of pages) {
+    if (!p.isTested) {
+      annotations.push(`::warning title=Missing E2E Spec::Frontend page ${p.routePath} has no e2e spec`)
+    }
+  }
+
+  for (const gap of ciGaps) {
+    annotations.push(`::warning title=CI Gap::${gap}`)
+  }
+
+  return annotations.join('\n')
+}
+
+// ============================================================================
+// MAIN AUDIT FUNCTION
+// ============================================================================
+
+/**
+ * Run the full test coverage audit.
+ */
+export async function runTestCoverageAudit(projectRoot) {
+  const [features, routes, pages, testFiles] = await Promise.all([
+    scanFeatureConfigs(projectRoot),
+    scanRoutes(projectRoot),
+    scanFrontendPages(projectRoot),
+    scanTestFiles(projectRoot),
+  ])
+
+  const ciChecks = scanCIPipeline(projectRoot)
+
+  const report = crossReference(features, routes, pages, testFiles, ciChecks)
+
+  return report
+}

package/lib/checks/health/index.js

@@ -1,5 +1,5 @@
 /**
- * Health Checks — All 28 project health checks
+ * Health Checks — All 29 project health checks
  *
  * Main entry: scanProjectHealth(projectPath, projectName, options?)
  * Individual checks available via named imports.
@@ -41,3 +41,4 @@ export { check as checkSecurityLayers } from './security-layers.js'
 export { check as checkSmokeReadiness } from './smoke-readiness.js'
 export { check as checkReleasePipeline } from './release-pipeline.js'
 export { check as checkTestStructure } from './test-structure.js'
+export { check as checkSentryMonitoring } from './sentry-monitoring.js'

package/lib/checks/health/rpc-param-mismatch.js

@@ -9,6 +9,27 @@
  *   - Low (missing params): -0.25 per finding (max -1)
  */
 
+// TODO(tetra-dev-toolkit): Add check 'table-mode-threshold'
+//
+// This check should warn when a feature uses table mode (no RPC names in FeatureConfig)
+// but the underlying Supabase table exceeds 50,000 rows — a signal that adding RPC
+// functions (get_*_results / get_*_counts) would improve query performance, especially
+// for breakdown count queries that currently fetch all rows into JS.
+//
+// Implementation sketch:
+//   1. Scan project for FeatureConfig objects that have no countsRpcName / resultsRpcName
+//   2. For each, query the Supabase API (using the project's service role key via Doppler)
+//      to get the row count: SELECT count(*) FROM <tableName>
+//   3. If count > 50_000, emit a warning with feature name, table name, and row count
+//   4. Score deduction: -0.5 per table over threshold (max -2)
+//
+// Prerequisites:
+//   - Doppler integration must be configured (checkDopplerCompliance passes)
+//   - Supabase project URL + service role key available at runtime
+//
+// See: packages/core/src/shared/services/TableQueryService.ts (>10k runtime warning)
+//      packages/core/src/shared/factories/QueryServiceFactory.ts (mode selection docs)
+
 import { createCheck } from './types.js'
 import { run as runAuditCheck } from '../supabase/rpc-param-mismatch.js'