@eduardbar/drift 1.2.0 → 1.4.0

package/src/plugins-rules.ts

@@ -0,0 +1,296 @@
+import type { DriftIssue, DriftPluginRule, PluginLoadError, PluginLoadWarning } from './types.js'
+import { pushError, pushWarning } from './plugins-messages.js'
+
+const VALID_SEVERITIES: DriftIssue['severity'][] = ['error', 'warning', 'info']
+const MAX_FIX_ARITY = 3
+const RULE_ID_REQUIRED = /^[a-z][a-z0-9]*(?:[-_/][a-z0-9]+)*$/
+
+type RuleCandidate = {
+  id?: unknown
+  name?: unknown
+  severity?: unknown
+  weight?: unknown
+  detect?: unknown
+  fix?: unknown
+}
+
+type NormalizeRuleContext = {
+  pluginId: string
+  pluginName: string
+  ruleIndex: number
+  strictRuleId: boolean
+  errors: PluginLoadError[]
+  warnings: PluginLoadWarning[]
+}
+
+type RuleValidationContext = {
+  pluginId: string
+  pluginName: string
+  ruleId: string
+  errors: PluginLoadError[]
+}
+
+type RuleMessageContext = {
+  pluginId: string
+  pluginName: string
+  ruleId: string
+  errors: PluginLoadError[]
+  warnings: PluginLoadWarning[]
+}
+
+export type PluginValidationContext = {
+  pluginId: string
+  pluginName: string
+  errors: PluginLoadError[]
+  warnings: PluginLoadWarning[]
+}
+
+function resolveRawRuleId(rawRule: RuleCandidate): string {
+  if (typeof rawRule.id === 'string') return rawRule.id.trim()
+  if (typeof rawRule.name === 'string') return rawRule.name.trim()
+  return ''
+}
+
+function ensureRuleId(
+  rawRuleId: string,
+  ruleIndex: number,
+  context: RuleMessageContext,
+): boolean {
+  if (rawRuleId) return true
+
+  pushError(
+    context.errors,
+    context.pluginId,
+    `Invalid rule at index ${ruleIndex}. Expected 'id' or 'name' as a non-empty string.`,
+    { pluginName: context.pluginName, code: 'plugin-rule-id-missing' },
+  )
+  return false
+}
+
+function ensureDetectFunction(
+  detect: unknown,
+  context: RuleMessageContext,
+): detect is DriftPluginRule['detect'] {
+  if (typeof detect === 'function') return true
+
+  pushError(
+    context.errors,
+    context.pluginId,
+    `Rule '${context.ruleId}' is invalid. Expected 'detect(file, context)' function.`,
+    { pluginName: context.pluginName, ruleId: context.ruleId, code: 'plugin-rule-detect-invalid' },
+  )
+  return false
+}
+
+function warnDetectArity(
+  detect: DriftPluginRule['detect'],
+  context: RuleMessageContext,
+): void {
+  if (detect.length <= 2) return
+
+  pushWarning(
+    context.warnings,
+    context.pluginId,
+    `Rule '${context.ruleId}' detect() declares ${detect.length} parameters. Expected 1-2 parameters (file, context).`,
+    { pluginName: context.pluginName, ruleId: context.ruleId, code: 'plugin-rule-detect-arity' },
+  )
+}
+
+function validateRuleIdentifierFormat(
+  rawRuleId: string,
+  strictRuleId: boolean,
+  context: RuleMessageContext,
+): void {
+  if (RULE_ID_REQUIRED.test(rawRuleId)) return
+  const ruleLabel = rawRuleId || 'unknown-rule'
+
+  if (strictRuleId) {
+    pushError(
+      context.errors,
+      context.pluginId,
+      `Rule id '${ruleLabel}' is invalid. Use lowercase letters, numbers, and separators (-, _, /), starting with a letter.`,
+      { pluginName: context.pluginName, ruleId: rawRuleId, code: 'plugin-rule-id-invalid' },
+    )
+    return
+  }
+
+  pushWarning(
+    context.warnings,
+    context.pluginId,
+    `Rule id '${ruleLabel}' uses a legacy format. For forward compatibility, migrate to lowercase kebab-case and set apiVersion: 1.`,
+    { pluginName: context.pluginName, ruleId: rawRuleId, code: 'plugin-rule-id-format-legacy' },
+  )
+}
+
+function resolveRuleSeverity(
+  rawSeverity: unknown,
+  context: RuleValidationContext,
+): DriftIssue['severity'] | undefined {
+  if (rawSeverity === undefined) return undefined
+  if (typeof rawSeverity === 'string' && VALID_SEVERITIES.includes(rawSeverity as DriftIssue['severity'])) {
+    return rawSeverity as DriftIssue['severity']
+  }
+
+  pushError(
+    context.errors,
+    context.pluginId,
+    `Rule '${context.ruleId}' has invalid severity '${String(rawSeverity)}'. Allowed: error, warning, info.`,
+    { pluginName: context.pluginName, ruleId: context.ruleId, code: 'plugin-rule-severity-invalid' },
+  )
+  return undefined
+}
+
+function resolveRuleWeight(rawWeight: unknown, context: RuleValidationContext): number | undefined {
+  if (rawWeight === undefined) return undefined
+  if (typeof rawWeight === 'number' && Number.isFinite(rawWeight) && rawWeight >= 0 && rawWeight <= 100) {
+    return rawWeight
+  }
+
+  pushError(
+    context.errors,
+    context.pluginId,
+    `Rule '${context.ruleId}' has invalid weight '${String(rawWeight)}'. Expected a finite number between 0 and 100.`,
+    { pluginName: context.pluginName, ruleId: context.ruleId, code: 'plugin-rule-weight-invalid' },
+  )
+  return undefined
+}
+
+function resolveRuleFix(
+  rawFix: unknown,
+  context: RuleMessageContext,
+): DriftPluginRule['fix'] | undefined {
+  if (rawFix === undefined) return undefined
+  if (typeof rawFix !== 'function') {
+    pushError(
+      context.errors,
+      context.pluginId,
+      `Rule '${context.ruleId}' has invalid fix. Expected a function when provided.`,
+      { pluginName: context.pluginName, ruleId: context.ruleId, code: 'plugin-rule-fix-invalid' },
+    )
+    return undefined
+  }
+
+  if (rawFix.length > MAX_FIX_ARITY) {
+    pushWarning(
+      context.warnings,
+      context.pluginId,
+      `Rule '${context.ruleId}' fix() declares ${rawFix.length} parameters. Expected up to ${MAX_FIX_ARITY} (issue, file, context).`,
+      { pluginName: context.pluginName, ruleId: context.ruleId, code: 'plugin-rule-fix-arity' },
+    )
+  }
+
+  return rawFix as DriftPluginRule['fix']
+}
+
+function normalizeRule(
+  rawRule: RuleCandidate,
+  context: NormalizeRuleContext,
+): DriftPluginRule | undefined {
+  const { pluginId, pluginName, ruleIndex, strictRuleId, errors, warnings } = context
+  const rawRuleId = resolveRawRuleId(rawRule)
+  const messageContext = { pluginId, pluginName, ruleId: rawRuleId, errors, warnings }
+  if (!ensureRuleId(rawRuleId, ruleIndex, messageContext)) return undefined
+  if (!ensureDetectFunction(rawRule.detect, messageContext)) return undefined
+
+  validateRuleIdentifierFormat(rawRuleId, strictRuleId, messageContext)
+  warnDetectArity(rawRule.detect, messageContext)
+  const ruleValidationContext: RuleValidationContext = { pluginId, pluginName, ruleId: rawRuleId, errors }
+  const severity = resolveRuleSeverity(rawRule.severity, ruleValidationContext)
+  const weight = resolveRuleWeight(rawRule.weight, ruleValidationContext)
+  const fix = resolveRuleFix(rawRule.fix, messageContext)
+
+  return {
+    id: rawRuleId,
+    name: rawRuleId,
+    detect: rawRule.detect as DriftPluginRule['detect'],
+    severity,
+    weight,
+    fix,
+  }
+}
+
+function ensureUniqueRuleId(
+  rule: DriftPluginRule,
+  seenRuleIds: Set<string>,
+  context: PluginValidationContext,
+): boolean {
+  const normalizedRuleId = rule.id ?? rule.name
+  if (seenRuleIds.has(normalizedRuleId)) {
+    pushError(
+      context.errors,
+      context.pluginId,
+      `Plugin '${context.pluginName}' defines duplicate rule id '${normalizedRuleId}'. Rule ids must be unique within a plugin.`,
+      { pluginName: context.pluginName, ruleId: normalizedRuleId, code: 'plugin-rule-id-duplicate' },
+    )
+    return false
+  }
+
+  seenRuleIds.add(normalizedRuleId)
+  return true
+}
+
+function normalizeRulesArray(
+  rulesCandidate: unknown[],
+  context: PluginValidationContext,
+  strictRuleId: boolean,
+): DriftPluginRule[] {
+  const normalizedRules: DriftPluginRule[] = []
+  const seenRuleIds = new Set<string>()
+
+  for (const [ruleIndex, rawRule] of rulesCandidate.entries()) {
+    if (!rawRule || typeof rawRule !== 'object') {
+      pushError(
+        context.errors,
+        context.pluginId,
+        `Invalid rule at index ${ruleIndex} in plugin '${context.pluginName}'. Expected an object.`,
+        { pluginName: context.pluginName, code: 'plugin-rule-shape-invalid' },
+      )
+      continue
+    }
+
+    const normalized = normalizeRule(rawRule as RuleCandidate, {
+      pluginId: context.pluginId,
+      pluginName: context.pluginName,
+      ruleIndex,
+      strictRuleId,
+      errors: context.errors,
+      warnings: context.warnings,
+    })
+
+    if (!normalized) continue
+    if (ensureUniqueRuleId(normalized, seenRuleIds, context)) {
+      normalizedRules.push(normalized)
+    }
+  }
+
+  return normalizedRules
+}
+
+export function normalizeRules(
+  rulesCandidate: unknown,
+  isLegacyPlugin: boolean,
+  context: PluginValidationContext,
+): DriftPluginRule[] | undefined {
+  if (!Array.isArray(rulesCandidate)) {
+    pushError(
+      context.errors,
+      context.pluginId,
+      `Invalid plugin '${context.pluginName}'. Expected 'rules' to be an array.`,
+      { pluginName: context.pluginName, code: 'plugin-rules-not-array' },
+    )
+    return undefined
+  }
+
+  const normalizedRules = normalizeRulesArray(rulesCandidate, context, !isLegacyPlugin)
+  if (normalizedRules.length === 0) {
+    pushError(
+      context.errors,
+      context.pluginId,
+      `Plugin '${context.pluginName}' has no valid rules after validation.`,
+      { pluginName: context.pluginName, code: 'plugin-rules-empty' },
+    )
+    return undefined
+  }
+
+  return normalizedRules
+}

package/src/plugins.ts

@@ -1,32 +1,151 @@
 import { existsSync } from 'node:fs'
 import { isAbsolute, resolve } from 'node:path'
 import { createRequire } from 'node:module'
-import type { DriftPlugin, PluginLoadError, 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 SUPPORTED_PLUGIN_API_VERSION = 1
 
-function isPluginShape(value: unknown): value is DriftPlugin {
-  if (!value || typeof value !== 'object') return false
-  const candidate = value as Partial<DriftPlugin>
-  if (typeof candidate.name !== 'string') return false
-  if (!Array.isArray(candidate.rules)) return false
-  return candidate.rules.every((rule) =>
-    rule &&
-    typeof rule === 'object' &&
-    typeof rule.name === 'string' &&
-    typeof rule.detect === 'function'
-  )
+type PluginCandidate = {
+  name?: unknown
+  apiVersion?: unknown
+  capabilities?: unknown
+  rules?: unknown
 }
 
-function normalizePluginExport(mod: unknown): DriftPlugin | undefined {
-  if (isPluginShape(mod)) return mod
+function normalizePluginExport(mod: unknown): unknown {
   if (mod && typeof mod === 'object' && 'default' in mod) {
-    const maybeDefault = (mod as { default?: unknown }).default
-    if (isPluginShape(maybeDefault)) return maybeDefault
+    return (mod as { default?: unknown }).default ?? mod
   }
+  return mod
+}
+
+function ensureObjectCandidate(
+  pluginId: string,
+  candidate: unknown,
+  errors: PluginLoadError[],
+): PluginCandidate | undefined {
+  if (candidate && typeof candidate === 'object') {
+    return candidate as PluginCandidate
+  }
+
+  pushError(
+    errors,
+    pluginId,
+    `Invalid plugin contract in '${pluginId}'. Expected an object export with shape { name, rules[] }`,
+    { code: 'plugin-shape-invalid' },
+  )
   return undefined
 }
 
+function ensurePluginName(
+  pluginId: string,
+  plugin: PluginCandidate,
+  errors: PluginLoadError[],
+): string | undefined {
+  const pluginName = typeof plugin.name === 'string' ? plugin.name.trim() : ''
+  if (pluginName) return pluginName
+
+  pushError(
+    errors,
+    pluginId,
+    `Invalid plugin contract in '${pluginId}'. Expected 'name' as a non-empty string.`,
+    { code: 'plugin-name-missing' },
+  )
+  return undefined
+}
+
+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
+
+  if (isLegacyPlugin) {
+    pushWarning(
+      warnings,
+      pluginId,
+      `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' },
+    )
+    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 { 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 { hasExplicitApiVersion, isLegacyPlugin, isSupported: false }
+  }
+
+  return { hasExplicitApiVersion, isLegacyPlugin, isSupported: true }
+}
+
+function validatePluginContractData(pluginId: string, candidate: unknown): {
+  plugin?: DriftPlugin
+  errors: PluginLoadError[]
+  warnings: PluginLoadWarning[]
+} {
+  const errors: PluginLoadError[] = []
+  const warnings: PluginLoadWarning[] = []
+
+  const plugin = ensureObjectCandidate(pluginId, candidate, errors)
+  if (!plugin) return { errors, warnings }
+
+  const pluginName = ensurePluginName(pluginId, plugin, errors)
+  if (!pluginName) return { errors, warnings }
+
+  const context: PluginValidationContext = { pluginId, pluginName, errors, warnings }
+  const apiVersion = validateApiVersion(plugin, context)
+  if (!apiVersion.isSupported) return { errors, warnings }
+
+  const capabilities = validateCapabilities(plugin.capabilities, context)
+  if (errors.length > 0) return { errors, warnings }
+
+  const normalizedRules = normalizeRules(plugin.rules, apiVersion.isLegacyPlugin, context)
+  if (!normalizedRules) return { errors, warnings }
+
+  return {
+    plugin: {
+      name: pluginName,
+      apiVersion: apiVersion.hasExplicitApiVersion ? plugin.apiVersion as number : SUPPORTED_PLUGIN_API_VERSION,
+      capabilities,
+      rules: normalizedRules,
+    },
+    errors,
+    warnings,
+  }
+}
+
+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)
@@ -43,34 +162,36 @@ function resolvePluginSpecifier(projectRoot: string, pluginId: string): string {
 export function loadPlugins(projectRoot: string, pluginIds: string[] | undefined): {
   plugins: LoadedPlugin[]
   errors: PluginLoadError[]
+  warnings: PluginLoadWarning[]
 } {
   if (!pluginIds || pluginIds.length === 0) {
-    return { plugins: [], errors: [] }
+    return { plugins: [], errors: [], warnings: [] }
   }
 
   const loaded: LoadedPlugin[] = []
   const errors: PluginLoadError[] = []
+  const warnings: PluginLoadWarning[] = []
 
   for (const pluginId of pluginIds) {
     const resolved = resolvePluginSpecifier(projectRoot, pluginId)
     try {
       const mod = require(resolved)
-      const plugin = normalizePluginExport(mod)
-      if (!plugin) {
-        errors.push({
-          pluginId,
-          message: `Invalid plugin contract in '${pluginId}'. Expected: { name, rules[] }`,
-        })
-        continue
-      }
-      loaded.push({ id: pluginId, plugin })
+      const normalized = normalizePluginExport(mod)
+      const validation = validatePluginContract(pluginId, normalized)
+
+      errors.push(...validation.errors)
+      warnings.push(...validation.warnings)
+
+      if (!validation.plugin) continue
+      loaded.push({ id: pluginId, plugin: validation.plugin })
     } catch (error) {
       errors.push({
         pluginId,
+        code: 'plugin-load-failed',
         message: error instanceof Error ? error.message : String(error),
       })
     }
   }
 
-  return { plugins: loaded, errors }
+  return { plugins: loaded, errors, warnings }
 }

package/src/printer.ts

@@ -133,6 +133,10 @@ function formatFixSuggestion(issue: DriftIssue): string[] {
       'Fix or remove the failing plugin in drift.config.*',
       'Validate plugin contract: export { name, rules[] } and detector functions',
     ],
+    'plugin-warning': [
+      'Review plugin validation warnings and align with the recommended contract',
+      'Use explicit rule ids and valid severity/weight values',
+    ],
   }
   return suggestions[issue.rule] ?? ['Review and fix manually']
 }

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 }