@eduardbar/drift 1.3.0 → 1.5.0

package/src/plugins.ts

@@ -1,12 +1,13 @@
 import { existsSync } from 'node:fs'
 import { isAbsolute, resolve } from 'node:path'
 import { createRequire } from 'node:module'
-import type { DriftIssue, DriftPlugin, DriftPluginRule, PluginLoadError, PluginLoadWarning, LoadedPlugin } from './types.js'
+import type { DriftPlugin, LoadedPlugin, PluginLoadError, PluginLoadWarning } from './types.js'
+import { normalizeRules, type PluginValidationContext } from './plugins-rules.js'
+import { validateCapabilities } from './plugins-capabilities.js'
+import { pushError, pushWarning } from './plugins-messages.js'
 
 const require = createRequire(import.meta.url)
-const VALID_SEVERITIES: DriftIssue['severity'][] = ['error', 'warning', 'info']
 const SUPPORTED_PLUGIN_API_VERSION = 1
-const RULE_ID_REQUIRED = /^[a-z][a-z0-9]*(?:[-_/][a-z0-9]+)*$/
 
 type PluginCandidate = {
   name?: unknown
@@ -15,15 +16,6 @@ type PluginCandidate = {
   rules?: unknown
 }
 
-type RuleCandidate = {
-  id?: unknown
-  name?: unknown
-  severity?: unknown
-  weight?: unknown
-  detect?: unknown
-  fix?: unknown
-}
-
 function normalizePluginExport(mod: unknown): unknown {
   if (mod && typeof mod === 'object' && 'default' in mod) {
     return (mod as { default?: unknown }).default ?? mod
@@ -31,194 +23,46 @@ function normalizePluginExport(mod: unknown): unknown {
   return mod
 }
 
-function pushError(
-  errors: PluginLoadError[],
+function ensureObjectCandidate(
   pluginId: string,
-  message: string,
-  options?: { pluginName?: string; ruleId?: string; code?: string },
-): void {
-  errors.push({
-    pluginId,
-    pluginName: options?.pluginName,
-    ruleId: options?.ruleId,
-    code: options?.code,
-    message,
-  })
-}
+  candidate: unknown,
+  errors: PluginLoadError[],
+): PluginCandidate | undefined {
+  if (candidate && typeof candidate === 'object') {
+    return candidate as PluginCandidate
+  }
 
-function pushWarning(
-  warnings: PluginLoadWarning[],
-  pluginId: string,
-  message: string,
-  options?: { pluginName?: string; ruleId?: string; code?: string },
-): void {
-  warnings.push({
+  pushError(
+    errors,
     pluginId,
-    pluginName: options?.pluginName,
-    ruleId: options?.ruleId,
-    code: options?.code,
-    message,
-  })
+    `Invalid plugin contract in '${pluginId}'. Expected an object export with shape { name, rules[] }`,
+    { code: 'plugin-shape-invalid' },
+  )
+  return undefined
 }
 
-function normalizeRule(
+function ensurePluginName(
   pluginId: string,
-  pluginName: string,
-  rawRule: RuleCandidate,
-  ruleIndex: number,
-  options: { strictRuleId: boolean },
+  plugin: PluginCandidate,
   errors: PluginLoadError[],
-  warnings: PluginLoadWarning[],
-): DriftPluginRule | undefined {
-  const rawRuleId = typeof rawRule.id === 'string'
-    ? rawRule.id.trim()
-    : typeof rawRule.name === 'string'
-      ? rawRule.name.trim()
-      : ''
-
-  const ruleLabel = rawRuleId || `rule#${ruleIndex + 1}`
-
-  if (!rawRuleId) {
-    pushError(
-      errors,
-      pluginId,
-      `Invalid rule at index ${ruleIndex}. Expected 'id' or 'name' as a non-empty string.`,
-      { pluginName, code: 'plugin-rule-id-missing' },
-    )
-    return undefined
-  }
-
-  if (typeof rawRule.detect !== 'function') {
-    pushError(
-      errors,
-      pluginId,
-      `Rule '${rawRuleId}' is invalid. Expected 'detect(file, context)' function.`,
-      { pluginName, ruleId: rawRuleId, code: 'plugin-rule-detect-invalid' },
-    )
-    return undefined
-  }
-
-  if (rawRule.detect.length > 2) {
-    pushWarning(
-      warnings,
-      pluginId,
-      `Rule '${rawRuleId}' detect() declares ${rawRule.detect.length} parameters. Expected 1-2 parameters (file, context).`,
-      { pluginName, ruleId: rawRuleId, code: 'plugin-rule-detect-arity' },
-    )
-  }
-
-  if (!RULE_ID_REQUIRED.test(rawRuleId)) {
-    if (options.strictRuleId) {
-      pushError(
-        errors,
-        pluginId,
-        `Rule id '${ruleLabel}' is invalid. Use lowercase letters, numbers, and separators (-, _, /), starting with a letter.`,
-        { pluginName, ruleId: rawRuleId, code: 'plugin-rule-id-invalid' },
-      )
-      return undefined
-    }
-
-    pushWarning(
-      warnings,
-      pluginId,
-      `Rule id '${ruleLabel}' uses a legacy format. For forward compatibility, migrate to lowercase kebab-case and set apiVersion: ${SUPPORTED_PLUGIN_API_VERSION}.`,
-      { pluginName, ruleId: rawRuleId, code: 'plugin-rule-id-format-legacy' },
-    )
-  }
-
-  let severity: DriftIssue['severity'] | undefined
-  if (rawRule.severity !== undefined) {
-    if (typeof rawRule.severity === 'string' && VALID_SEVERITIES.includes(rawRule.severity as DriftIssue['severity'])) {
-      severity = rawRule.severity as DriftIssue['severity']
-    } else {
-      pushError(
-        errors,
-        pluginId,
-        `Rule '${rawRuleId}' has invalid severity '${String(rawRule.severity)}'. Allowed: error, warning, info.`,
-        { pluginName, ruleId: rawRuleId, code: 'plugin-rule-severity-invalid' },
-      )
-    }
-  }
-
-  let weight: number | undefined
-  if (rawRule.weight !== undefined) {
-    if (typeof rawRule.weight === 'number' && Number.isFinite(rawRule.weight) && rawRule.weight >= 0 && rawRule.weight <= 100) {
-      weight = rawRule.weight
-    } else {
-      pushError(
-        errors,
-        pluginId,
-        `Rule '${rawRuleId}' has invalid weight '${String(rawRule.weight)}'. Expected a finite number between 0 and 100.`,
-        { pluginName, ruleId: rawRuleId, code: 'plugin-rule-weight-invalid' },
-      )
-    }
-  }
-
-  let fix: DriftPluginRule['fix'] | undefined
-  if (rawRule.fix !== undefined) {
-    if (typeof rawRule.fix === 'function') {
-      fix = rawRule.fix as DriftPluginRule['fix']
-      if (rawRule.fix.length > 3) {
-        pushWarning(
-          warnings,
-          pluginId,
-          `Rule '${rawRuleId}' fix() declares ${rawRule.fix.length} parameters. Expected up to 3 (issue, file, context).`,
-          { pluginName, ruleId: rawRuleId, code: 'plugin-rule-fix-arity' },
-        )
-      }
-    } else {
-      pushError(
-        errors,
-        pluginId,
-        `Rule '${rawRuleId}' has invalid fix. Expected a function when provided.`,
-        { pluginName, ruleId: rawRuleId, code: 'plugin-rule-fix-invalid' },
-      )
-    }
-  }
+): string | undefined {
+  const pluginName = typeof plugin.name === 'string' ? plugin.name.trim() : ''
+  if (pluginName) return pluginName
 
-  return {
-    id: rawRuleId,
-    name: rawRuleId,
-    detect: rawRule.detect as DriftPluginRule['detect'],
-    severity,
-    weight,
-    fix,
-  }
+  pushError(
+    errors,
+    pluginId,
+    `Invalid plugin contract in '${pluginId}'. Expected 'name' as a non-empty string.`,
+    { code: 'plugin-name-missing' },
+  )
+  return undefined
 }
 
-function validatePluginContract(
-  pluginId: string,
-  candidate: unknown,
-): {
-  plugin?: DriftPlugin
-  errors: PluginLoadError[]
-  warnings: PluginLoadWarning[]
-} {
-  const errors: PluginLoadError[] = []
-  const warnings: PluginLoadWarning[] = []
-
-  if (!candidate || typeof candidate !== 'object') {
-    pushError(
-      errors,
-      pluginId,
-      `Invalid plugin contract in '${pluginId}'. Expected an object export with shape { name, rules[] }`,
-      { code: 'plugin-shape-invalid' },
-    )
-    return { errors, warnings }
-  }
-
-  const plugin = candidate as PluginCandidate
-  const pluginName = typeof plugin.name === 'string' ? plugin.name.trim() : ''
-  if (!pluginName) {
-    pushError(
-      errors,
-      pluginId,
-      `Invalid plugin contract in '${pluginId}'. Expected 'name' as a non-empty string.`,
-      { code: 'plugin-name-missing' },
-    )
-    return { errors, warnings }
-  }
-
+function validateApiVersion(
+  plugin: PluginCandidate,
+  context: PluginValidationContext,
+): { hasExplicitApiVersion: boolean; isLegacyPlugin: boolean; isSupported: boolean } {
+  const { pluginId, pluginName, errors, warnings } = context
   const hasExplicitApiVersion = plugin.apiVersion !== undefined
   const isLegacyPlugin = !hasExplicitApiVersion
 
@@ -229,119 +73,60 @@ function validatePluginContract(
       `Plugin '${pluginName}' does not declare 'apiVersion'. Assuming ${SUPPORTED_PLUGIN_API_VERSION} for backward compatibility; please add apiVersion: ${SUPPORTED_PLUGIN_API_VERSION}.`,
       { pluginName, code: 'plugin-api-version-implicit' },
     )
-  } else if (typeof plugin.apiVersion !== 'number' || !Number.isInteger(plugin.apiVersion) || plugin.apiVersion <= 0) {
+    return { hasExplicitApiVersion, isLegacyPlugin, isSupported: true }
+  }
+
+  if (typeof plugin.apiVersion !== 'number' || !Number.isInteger(plugin.apiVersion) || plugin.apiVersion <= 0) {
     pushError(
       errors,
       pluginId,
       `Plugin '${pluginName}' has invalid apiVersion '${String(plugin.apiVersion)}'. Expected a positive integer (for example: ${SUPPORTED_PLUGIN_API_VERSION}).`,
       { pluginName, code: 'plugin-api-version-invalid' },
     )
-    return { errors, warnings }
-  } else if (plugin.apiVersion !== SUPPORTED_PLUGIN_API_VERSION) {
+    return { hasExplicitApiVersion, isLegacyPlugin, isSupported: false }
+  }
+
+  if (plugin.apiVersion !== SUPPORTED_PLUGIN_API_VERSION) {
     pushError(
       errors,
       pluginId,
       `Plugin '${pluginName}' targets apiVersion ${plugin.apiVersion}, but this drift build supports apiVersion ${SUPPORTED_PLUGIN_API_VERSION}.`,
       { pluginName, code: 'plugin-api-version-unsupported' },
     )
-    return { errors, warnings }
+    return { hasExplicitApiVersion, isLegacyPlugin, isSupported: false }
   }
 
-  let capabilities: DriftPlugin['capabilities'] | undefined
-  if (plugin.capabilities !== undefined) {
-    if (!plugin.capabilities || typeof plugin.capabilities !== 'object' || Array.isArray(plugin.capabilities)) {
-      pushError(
-        errors,
-        pluginId,
-        `Plugin '${pluginName}' has invalid capabilities metadata. Expected an object map like { "fixes": true } when provided.`,
-        { pluginName, code: 'plugin-capabilities-invalid' },
-      )
-      return { errors, warnings }
-    }
-
-    const entries = Object.entries(plugin.capabilities as Record<string, unknown>)
-    for (const [capabilityKey, capabilityValue] of entries) {
-      const capabilityType = typeof capabilityValue
-      if (capabilityType !== 'string' && capabilityType !== 'number' && capabilityType !== 'boolean') {
-        pushError(
-          errors,
-          pluginId,
-          `Plugin '${pluginName}' capability '${capabilityKey}' has invalid value type '${capabilityType}'. Allowed: string | number | boolean.`,
-          { pluginName, code: 'plugin-capabilities-value-invalid' },
-        )
-      }
-    }
-
-    if (errors.length > 0) {
-      return { errors, warnings }
-    }
-
-    capabilities = plugin.capabilities as DriftPlugin['capabilities']
-  }
+  return { hasExplicitApiVersion, isLegacyPlugin, isSupported: true }
+}
 
-  if (!Array.isArray(plugin.rules)) {
-    pushError(
-      errors,
-      pluginId,
-      `Invalid plugin '${pluginName}'. Expected 'rules' to be an array.`,
-      { pluginName, code: 'plugin-rules-not-array' },
-    )
-    return { errors, warnings }
-  }
+function validatePluginContractData(pluginId: string, candidate: unknown): {
+  plugin?: DriftPlugin
+  errors: PluginLoadError[]
+  warnings: PluginLoadWarning[]
+} {
+  const errors: PluginLoadError[] = []
+  const warnings: PluginLoadWarning[] = []
 
-  const normalizedRules: DriftPluginRule[] = []
-  const seenRuleIds = new Set<string>()
+  const plugin = ensureObjectCandidate(pluginId, candidate, errors)
+  if (!plugin) return { errors, warnings }
 
-  for (const [ruleIndex, rawRule] of plugin.rules.entries()) {
-    if (!rawRule || typeof rawRule !== 'object') {
-      pushError(
-        errors,
-        pluginId,
-        `Invalid rule at index ${ruleIndex} in plugin '${pluginName}'. Expected an object.`,
-        { pluginName, code: 'plugin-rule-shape-invalid' },
-      )
-      continue
-    }
+  const pluginName = ensurePluginName(pluginId, plugin, errors)
+  if (!pluginName) return { errors, warnings }
 
-    const normalized = normalizeRule(
-      pluginId,
-      pluginName,
-      rawRule as RuleCandidate,
-      ruleIndex,
-      { strictRuleId: !isLegacyPlugin },
-      errors,
-      warnings,
-    )
-    if (normalized) {
-      if (seenRuleIds.has(normalized.id ?? normalized.name)) {
-        pushError(
-          errors,
-          pluginId,
-          `Plugin '${pluginName}' defines duplicate rule id '${normalized.id ?? normalized.name}'. Rule ids must be unique within a plugin.`,
-          { pluginName, ruleId: normalized.id ?? normalized.name, code: 'plugin-rule-id-duplicate' },
-        )
-        continue
-      }
+  const context: PluginValidationContext = { pluginId, pluginName, errors, warnings }
+  const apiVersion = validateApiVersion(plugin, context)
+  if (!apiVersion.isSupported) return { errors, warnings }
 
-      seenRuleIds.add(normalized.id ?? normalized.name)
-      normalizedRules.push(normalized)
-    }
-  }
+  const capabilities = validateCapabilities(plugin.capabilities, context)
+  if (errors.length > 0) return { errors, warnings }
 
-  if (normalizedRules.length === 0) {
-    pushError(
-      errors,
-      pluginId,
-      `Plugin '${pluginName}' has no valid rules after validation.`,
-      { pluginName, code: 'plugin-rules-empty' },
-    )
-    return { errors, warnings }
-  }
+  const normalizedRules = normalizeRules(plugin.rules, apiVersion.isLegacyPlugin, context)
+  if (!normalizedRules) return { errors, warnings }
 
   return {
     plugin: {
       name: pluginName,
-      apiVersion: hasExplicitApiVersion ? plugin.apiVersion as number : SUPPORTED_PLUGIN_API_VERSION,
+      apiVersion: apiVersion.hasExplicitApiVersion ? plugin.apiVersion as number : SUPPORTED_PLUGIN_API_VERSION,
       capabilities,
       rules: normalizedRules,
     },
@@ -350,6 +135,17 @@ function validatePluginContract(
   }
 }
 
+function validatePluginContract(
+  pluginId: string,
+  candidate: unknown,
+): {
+  plugin?: DriftPlugin
+  errors: PluginLoadError[]
+  warnings: PluginLoadWarning[]
+} {
+  return validatePluginContractData(pluginId, candidate)
+}
+
 function resolvePluginSpecifier(projectRoot: string, pluginId: string): string {
   if (pluginId.startsWith('.') || pluginId.startsWith('/')) {
     const abs = isAbsolute(pluginId) ? pluginId : resolve(projectRoot, pluginId)
@@ -386,10 +182,7 @@ export function loadPlugins(projectRoot: string, pluginIds: string[] | undefined
       errors.push(...validation.errors)
       warnings.push(...validation.warnings)
 
-      if (!validation.plugin) {
-        continue
-      }
-
+      if (!validation.plugin) continue
       loaded.push({ id: pluginId, plugin: validation.plugin })
     } catch (error) {
       errors.push({

package/src/reporter-constants.ts

@@ -0,0 +1,46 @@
+import type { DriftIssue } from './types.js'
+
+export 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',
+}
+
+export 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',
+}
+
+export const SEVERITY_ORDER: Record<string, number> = { error: 0, warning: 1, info: 2 }
+export const EFFORT_ORDER: Record<string, number> = { low: 0, medium: 1, high: 2 }
+
+export 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 const AI_CODE_SMELL_BOOST = 20
+export const AI_TRIGGER_LIMIT = 4
+export const AI_LIKELIHOOD_THRESHOLD = 35
+export const AI_SMELL_SCORE_MULTIPLIER = 15
+export const AI_SUSPECTED_LIMIT = 10
+
+export type DriftIssueWithFile = { file: string; issue: DriftIssue }