fcis 0.1.0

package/src/detection/markers.ts

@@ -0,0 +1,332 @@
+/**
+ * Marker Definitions and Catalog
+ *
+ * This module defines the impurity marker types and provides a catalog
+ * of patterns for detecting each marker type. This is PURE code - all
+ * functions take data in and return data out with no I/O.
+ *
+ * The marker catalog is defined as a data structure to enable:
+ * - Extensibility (custom markers can be added)
+ * - Documentation (each marker has a description)
+ * - Testing (patterns can be validated in isolation)
+ */
+
+import type { MarkerType } from '../types.js'
+
+/**
+ * Marker definition with detection patterns
+ */
+export type MarkerDefinition = {
+  type: MarkerType
+  description: string
+  category: 'io' | 'state' | 'side-effect' | 'environment'
+  severity: 'high' | 'medium' | 'low'
+}
+
+/**
+ * Database operations that indicate I/O
+ */
+export const DATABASE_OPERATIONS = new Set([
+  'findFirst',
+  'findMany',
+  'findUnique',
+  'findUniqueOrThrow',
+  'findFirstOrThrow',
+  'create',
+  'createMany',
+  'update',
+  'updateMany',
+  'delete',
+  'deleteMany',
+  'upsert',
+  'aggregate',
+  'count',
+  'groupBy',
+  '$transaction',
+  '$queryRaw',
+  '$executeRaw',
+])
+
+/**
+ * Database client prefixes
+ */
+export const DATABASE_PREFIXES = ['db', 'prisma', 'ctx.db', 'ctx.prisma']
+
+/**
+ * File system modules that indicate I/O
+ */
+export const FS_MODULES = new Set([
+  'fs',
+  'node:fs',
+  'fs/promises',
+  'node:fs/promises',
+])
+
+/**
+ * HTTP client modules
+ */
+export const HTTP_MODULES = new Set(['axios', 'node-fetch', 'got', 'ky'])
+
+/**
+ * Console methods that indicate logging
+ */
+export const CONSOLE_METHODS = new Set([
+  'log',
+  'error',
+  'warn',
+  'info',
+  'debug',
+  'trace',
+])
+
+/**
+ * Analytics/telemetry function patterns
+ */
+export const TELEMETRY_PATTERNS = [
+  /^track[A-Z]/,
+  /^analytics\./,
+  /^segment\./,
+  /^posthog\./,
+  /^mixpanel\./,
+  /^amplitude\./,
+]
+
+/**
+ * Marker catalog - all recognized impurity markers
+ */
+export const MARKER_CATALOG: Record<MarkerType, MarkerDefinition> = {
+  'await-expression': {
+    type: 'await-expression',
+    description: 'Await expression indicates I/O suspension point',
+    category: 'io',
+    severity: 'high',
+  },
+  'database-call': {
+    type: 'database-call',
+    description: 'Database operation (Prisma/similar ORM call)',
+    category: 'io',
+    severity: 'high',
+  },
+  'network-fetch': {
+    type: 'network-fetch',
+    description: 'Native fetch() call for HTTP requests',
+    category: 'io',
+    severity: 'high',
+  },
+  'network-http': {
+    type: 'network-http',
+    description: 'HTTP client library call (axios, got, etc.)',
+    category: 'io',
+    severity: 'high',
+  },
+  'fs-import': {
+    type: 'fs-import',
+    description: 'Import from file system module',
+    category: 'io',
+    severity: 'medium',
+  },
+  'fs-call': {
+    type: 'fs-call',
+    description: 'File system operation call',
+    category: 'io',
+    severity: 'high',
+  },
+  'env-access': {
+    type: 'env-access',
+    description: 'Access to process.env environment variables',
+    category: 'environment',
+    severity: 'medium',
+  },
+  'console-log': {
+    type: 'console-log',
+    description: 'Console logging call',
+    category: 'side-effect',
+    severity: 'low',
+  },
+  logging: {
+    type: 'logging',
+    description: 'Logger service call',
+    category: 'side-effect',
+    severity: 'low',
+  },
+  telemetry: {
+    type: 'telemetry',
+    description: 'Analytics/tracking/telemetry call',
+    category: 'side-effect',
+    severity: 'low',
+  },
+  'queue-enqueue': {
+    type: 'queue-enqueue',
+    description: 'Message queue enqueue operation',
+    category: 'io',
+    severity: 'high',
+  },
+  'event-emit': {
+    type: 'event-emit',
+    description: 'Event emitter emit call',
+    category: 'side-effect',
+    severity: 'medium',
+  },
+}
+
+/**
+ * Get marker definition by type
+ */
+export function getMarkerDefinition(type: MarkerType): MarkerDefinition {
+  return MARKER_CATALOG[type]
+}
+
+/**
+ * Get all marker types
+ */
+export function getAllMarkerTypes(): MarkerType[] {
+  return Object.keys(MARKER_CATALOG) as MarkerType[]
+}
+
+/**
+ * Get markers by category
+ */
+export function getMarkersByCategory(
+  category: MarkerDefinition['category'],
+): MarkerDefinition[] {
+  return Object.values(MARKER_CATALOG).filter(m => m.category === category)
+}
+
+/**
+ * Get markers by severity
+ */
+export function getMarkersBySeverity(
+  severity: MarkerDefinition['severity'],
+): MarkerDefinition[] {
+  return Object.values(MARKER_CATALOG).filter(m => m.severity === severity)
+}
+
+/**
+ * Check if a call expression matches a database operation pattern
+ * e.g., "db.user.findFirst", "prisma.user.create", "ctx.db.user.update"
+ */
+export function isDatabaseCall(expression: string): boolean {
+  // Check if expression starts with a known database prefix
+  const lowerExpr = expression.toLowerCase()
+
+  for (const prefix of DATABASE_PREFIXES) {
+    if (lowerExpr.startsWith(prefix + '.')) {
+      // Extract the operation (last part of the chain)
+      const parts = expression.split('.')
+      const operation = parts[parts.length - 1]
+      if (operation && DATABASE_OPERATIONS.has(operation)) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+/**
+ * Check if a call expression is a fetch call
+ */
+export function isFetchCall(expression: string): boolean {
+  return expression === 'fetch' || expression.endsWith('.fetch')
+}
+
+/**
+ * Check if a call expression is an HTTP client call
+ */
+export function isHttpClientCall(
+  expression: string,
+  importedModules: Set<string>,
+): boolean {
+  // Check if axios or similar is imported
+  for (const module of HTTP_MODULES) {
+    if (importedModules.has(module)) {
+      // Check for axios.get, axios.post, etc.
+      if (
+        expression.startsWith('axios.') ||
+        expression === 'axios' ||
+        expression.startsWith('got.') ||
+        expression === 'got' ||
+        expression.startsWith('ky.')
+      ) {
+        return true
+      }
+    }
+  }
+
+  return false
+}
+
+/**
+ * Check if a call expression is a file system call
+ */
+export function isFsCall(expression: string): boolean {
+  return (
+    expression.startsWith('fs.') ||
+    expression.startsWith('fsPromises.') ||
+    expression.startsWith('fsp.')
+  )
+}
+
+/**
+ * Check if a module specifier is a file system module
+ */
+export function isFsModule(moduleSpecifier: string): boolean {
+  return FS_MODULES.has(moduleSpecifier)
+}
+
+/**
+ * Check if a property access is an environment variable access
+ */
+export function isEnvAccess(propertyChain: string): boolean {
+  return (
+    propertyChain.startsWith('process.env.') || propertyChain === 'process.env'
+  )
+}
+
+/**
+ * Check if a call expression is a console log call
+ */
+export function isConsoleCall(expression: string): boolean {
+  if (!expression.startsWith('console.')) return false
+
+  const method = expression.slice('console.'.length)
+  return CONSOLE_METHODS.has(method)
+}
+
+/**
+ * Check if a call expression is a logging call
+ */
+export function isLoggingCall(expression: string): boolean {
+  return (
+    expression.startsWith('logger.') ||
+    expression.startsWith('log.') ||
+    expression === 'log' ||
+    expression.startsWith('Logger.')
+  )
+}
+
+/**
+ * Check if a call expression is a telemetry/analytics call
+ */
+export function isTelemetryCall(expression: string): boolean {
+  for (const pattern of TELEMETRY_PATTERNS) {
+    if (pattern.test(expression)) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Check if a call expression is a queue enqueue call
+ */
+export function isQueueEnqueueCall(expression: string): boolean {
+  return expression.endsWith('.enqueue') || expression.endsWith('.add')
+}
+
+/**
+ * Check if a call expression is an event emit call
+ */
+export function isEventEmitCall(expression: string): boolean {
+  return expression.endsWith('.emit') || expression.endsWith('.dispatch')
+}