@bfra.me/workspace-analyzer 0.1.0

package/src/config/merger.ts

@@ -0,0 +1,229 @@
+/**
+ * Configuration merging utilities for workspace analyzer.
+ *
+ * Provides deep merging of configuration sources with proper precedence:
+ * programmatic options > config file > defaults
+ */
+
+import type {WorkspaceAnalyzerConfig} from './loader'
+import type {WorkspaceAnalyzerConfigOutput} from './schema'
+
+import {
+  DEFAULT_ANALYZER_CONFIG,
+  DEFAULT_CACHE_DIR,
+  DEFAULT_CONCURRENCY,
+  DEFAULT_HASH_ALGORITHM,
+  DEFAULT_MAX_CACHE_AGE,
+  DEFAULT_PACKAGE_PATTERNS,
+} from './defaults'
+
+/**
+ * Complete configuration after merging all sources.
+ */
+export interface MergedConfig {
+  /** Glob patterns for files to include */
+  readonly include: readonly string[]
+  /** Glob patterns for files to exclude */
+  readonly exclude: readonly string[]
+  /** Minimum severity level to report */
+  readonly minSeverity: 'info' | 'warning' | 'error' | 'critical'
+  /** Categories of issues to check (empty means all) */
+  readonly categories: readonly (
+    | 'configuration'
+    | 'dependency'
+    | 'architecture'
+    | 'performance'
+    | 'circular-import'
+    | 'unused-export'
+    | 'type-safety'
+  )[]
+  /** Enable incremental analysis caching */
+  readonly cache: boolean
+  /** Custom rules configuration */
+  readonly rules: Readonly<Record<string, unknown>>
+  /** Glob patterns for package locations */
+  readonly packagePatterns: readonly string[]
+  /** Maximum parallel analysis operations */
+  readonly concurrency: number
+  /** Directory for analysis cache files */
+  readonly cacheDir: string
+  /** Maximum cache age in milliseconds */
+  readonly maxCacheAge: number
+  /** Hash algorithm for file content */
+  readonly hashAlgorithm: 'sha256' | 'md5'
+  /** Per-analyzer configuration */
+  readonly analyzers: Readonly<
+    Record<
+      string,
+      {
+        readonly enabled?: boolean
+        readonly severity?: 'info' | 'warning' | 'error' | 'critical'
+        readonly options?: Readonly<Record<string, unknown>>
+      }
+    >
+  >
+  /** Architectural analysis rules */
+  readonly architecture?: {
+    readonly layers?: readonly {
+      readonly name: string
+      readonly patterns: readonly string[]
+      readonly allowedImports: readonly string[]
+    }[]
+    readonly allowBarrelExports?: boolean | readonly string[]
+    readonly enforcePublicApi?: boolean
+  }
+}
+
+/**
+ * Gets the default merged configuration.
+ */
+export function getDefaultMergedConfig(): MergedConfig {
+  return {
+    include: DEFAULT_ANALYZER_CONFIG.include,
+    exclude: DEFAULT_ANALYZER_CONFIG.exclude,
+    minSeverity: DEFAULT_ANALYZER_CONFIG.minSeverity,
+    categories: DEFAULT_ANALYZER_CONFIG.categories,
+    cache: DEFAULT_ANALYZER_CONFIG.cache,
+    rules: DEFAULT_ANALYZER_CONFIG.rules,
+    packagePatterns: DEFAULT_PACKAGE_PATTERNS,
+    concurrency: DEFAULT_CONCURRENCY,
+    cacheDir: DEFAULT_CACHE_DIR,
+    maxCacheAge: DEFAULT_MAX_CACHE_AGE,
+    hashAlgorithm: DEFAULT_HASH_ALGORITHM,
+    analyzers: {},
+    architecture: undefined,
+  }
+}
+
+/**
+ * Merges analyzer-specific configurations.
+ *
+ * @param baseAnalyzers - Base analyzer config from file
+ * @param overrideAnalyzers - Override config from programmatic options
+ * @returns Merged analyzer configurations
+ */
+export function mergeAnalyzerConfigs(
+  baseAnalyzers: MergedConfig['analyzers'],
+  overrideAnalyzers?: WorkspaceAnalyzerConfig['analyzers'],
+): MergedConfig['analyzers'] {
+  if (overrideAnalyzers == null) {
+    return baseAnalyzers
+  }
+
+  const merged = {...baseAnalyzers}
+
+  for (const [id, config] of Object.entries(overrideAnalyzers)) {
+    const base = merged[id]
+    if (base == null) {
+      merged[id] = config
+    } else {
+      merged[id] = {
+        ...base,
+        ...config,
+        options: config.options == null ? base.options : {...base.options, ...config.options},
+      }
+    }
+  }
+
+  return merged
+}
+
+/**
+ * Converts a validated config to a merged config structure.
+ */
+function validatedToMerged(config: WorkspaceAnalyzerConfigOutput): MergedConfig {
+  return {
+    include: config.include,
+    exclude: config.exclude,
+    minSeverity: config.minSeverity,
+    categories: config.categories,
+    cache: config.cache,
+    rules: config.rules,
+    packagePatterns: config.packagePatterns,
+    concurrency: config.concurrency,
+    cacheDir: config.cacheDir,
+    maxCacheAge: config.maxCacheAge,
+    hashAlgorithm: config.hashAlgorithm,
+    analyzers: config.analyzers,
+    architecture: config.architecture,
+  }
+}
+
+/**
+ * Applies partial options to a merged configuration.
+ */
+function applyOptions(base: MergedConfig, options: WorkspaceAnalyzerConfig): MergedConfig {
+  return {
+    include: options.include ?? base.include,
+    exclude: options.exclude ?? base.exclude,
+    minSeverity: options.minSeverity ?? base.minSeverity,
+    categories: options.categories ?? base.categories,
+    cache: options.cache ?? base.cache,
+    rules: options.rules == null ? base.rules : {...base.rules, ...options.rules},
+    packagePatterns: options.packagePatterns ?? base.packagePatterns,
+    concurrency: options.concurrency ?? base.concurrency,
+    cacheDir: options.cacheDir ?? base.cacheDir,
+    maxCacheAge: options.maxCacheAge ?? base.maxCacheAge,
+    hashAlgorithm: options.hashAlgorithm ?? base.hashAlgorithm,
+    analyzers: mergeAnalyzerConfigs(base.analyzers, options.analyzers),
+    architecture: options.architecture ?? base.architecture,
+  }
+}
+
+/**
+ * Merges configuration from multiple sources.
+ *
+ * Precedence (highest to lowest):
+ * 1. Programmatic options passed to analyzeWorkspace()
+ * 2. Configuration file (workspace-analyzer.config.ts)
+ * 3. Default values
+ *
+ * @param fileConfig - Configuration loaded from file (optional)
+ * @param programmaticOptions - Options passed programmatically (optional)
+ * @returns Fully merged configuration with all defaults applied
+ */
+export function mergeConfig(
+  fileConfig?: WorkspaceAnalyzerConfigOutput,
+  programmaticOptions?: WorkspaceAnalyzerConfig,
+): MergedConfig {
+  // Start with defaults
+  let merged = getDefaultMergedConfig()
+
+  // Apply file config if present
+  if (fileConfig != null) {
+    merged = validatedToMerged(fileConfig)
+  }
+
+  // Apply programmatic options with highest precedence
+  if (programmaticOptions != null) {
+    merged = applyOptions(merged, programmaticOptions)
+  }
+
+  return merged
+}
+
+/**
+ * Creates analyzer options from merged configuration for a specific analyzer.
+ *
+ * @param mergedConfig - The fully merged configuration
+ * @param analyzerId - The ID of the analyzer to get options for
+ * @returns Options for the specified analyzer
+ */
+export function getAnalyzerOptions(
+  mergedConfig: MergedConfig,
+  analyzerId: string,
+): {
+  enabled: boolean
+  minSeverity: MergedConfig['minSeverity']
+  categories: MergedConfig['categories']
+  options: Record<string, unknown>
+} {
+  const analyzerConfig = mergedConfig.analyzers[analyzerId]
+
+  return {
+    enabled: analyzerConfig?.enabled ?? true,
+    minSeverity: analyzerConfig?.severity ?? mergedConfig.minSeverity,
+    categories: mergedConfig.categories,
+    options: (analyzerConfig?.options ?? {}) as Record<string, unknown>,
+  }
+}

package/src/config/schema.ts

@@ -0,0 +1,263 @@
+/**
+ * Zod schemas for configuration validation.
+ *
+ * Provides runtime validation for workspace analyzer configuration,
+ * ensuring type safety and helpful error messages for invalid configs.
+ */
+
+import {z} from 'zod'
+
+import {
+  DEFAULT_ANALYZER_CONFIG,
+  DEFAULT_CACHE_DIR,
+  DEFAULT_CONCURRENCY,
+  DEFAULT_MAX_CACHE_AGE,
+  DEFAULT_PACKAGE_PATTERNS,
+} from './defaults'
+
+/**
+ * Valid severity levels for issue filtering.
+ */
+export const severitySchema = z.enum(['info', 'warning', 'error', 'critical'])
+
+/**
+ * Valid issue categories for filtering.
+ */
+export const categorySchema = z.enum([
+  'configuration',
+  'dependency',
+  'architecture',
+  'performance',
+  'circular-import',
+  'unused-export',
+  'type-safety',
+])
+
+/**
+ * Schema for custom rule configuration.
+ */
+export const ruleConfigSchema = z
+  .record(z.string(), z.unknown())
+  .describe('Custom rule configuration keyed by rule ID')
+
+/**
+ * Schema for analyzer-specific options.
+ */
+export const analyzerOptionsSchema = z
+  .object({
+    enabled: z.boolean().optional().describe('Whether this analyzer is enabled'),
+    severity: severitySchema.optional().describe('Override default severity'),
+    options: z.record(z.string(), z.unknown()).optional().describe('Analyzer-specific options'),
+  })
+  .strict()
+
+/**
+ * Schema for layer configuration in architectural analysis.
+ */
+export const layerConfigSchema = z.object({
+  name: z.string().describe('Layer name'),
+  patterns: z.array(z.string()).describe('File path patterns matching this layer'),
+  allowedImports: z.array(z.string()).describe('Layers this layer can import from'),
+})
+
+/**
+ * Schema for architectural rules configuration.
+ */
+export const architecturalRulesSchema = z
+  .object({
+    layers: z
+      .array(layerConfigSchema)
+      .optional()
+      .describe('Custom layer definitions for layer violation detection'),
+    allowBarrelExports: z
+      .union([z.boolean(), z.array(z.string())])
+      .optional()
+      .describe('Allow barrel exports (true/false or array of allowed paths)'),
+    enforcePublicApi: z.boolean().optional().describe('Enforce explicit public API exports'),
+  })
+  .strict()
+
+/**
+ * Core analyzer configuration schema.
+ */
+export const analyzerConfigSchema = z
+  .object({
+    include: z
+      .array(z.string())
+      .optional()
+      .default(DEFAULT_ANALYZER_CONFIG.include as unknown as string[])
+      .describe('Glob patterns for files to include in analysis'),
+    exclude: z
+      .array(z.string())
+      .optional()
+      .default(DEFAULT_ANALYZER_CONFIG.exclude as unknown as string[])
+      .describe('Glob patterns for files to exclude from analysis'),
+    minSeverity: severitySchema
+      .optional()
+      .default(DEFAULT_ANALYZER_CONFIG.minSeverity)
+      .describe('Minimum severity level to report'),
+    categories: z
+      .array(categorySchema)
+      .optional()
+      .default([])
+      .describe('Categories of issues to check (empty means all)'),
+    cache: z.boolean().optional().default(true).describe('Enable incremental analysis caching'),
+    rules: ruleConfigSchema.optional().default({}).describe('Custom rules configuration'),
+  })
+  .strict()
+
+/**
+ * Workspace-specific options schema.
+ */
+export const workspaceOptionsSchema = z
+  .object({
+    packagePatterns: z
+      .array(z.string())
+      .optional()
+      .default(DEFAULT_PACKAGE_PATTERNS as unknown as string[])
+      .describe('Glob patterns for package locations'),
+    concurrency: z
+      .number()
+      .int()
+      .min(1)
+      .max(16)
+      .optional()
+      .default(DEFAULT_CONCURRENCY)
+      .describe('Maximum parallel analysis operations'),
+    cacheDir: z
+      .string()
+      .optional()
+      .default(DEFAULT_CACHE_DIR)
+      .describe('Directory for analysis cache files'),
+    maxCacheAge: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .default(DEFAULT_MAX_CACHE_AGE)
+      .describe('Maximum cache age in milliseconds'),
+    hashAlgorithm: z
+      .enum(['sha256', 'md5'])
+      .optional()
+      .default('sha256')
+      .describe('Hash algorithm for file content'),
+  })
+  .strict()
+
+/**
+ * Per-analyzer configuration in the config file.
+ */
+export const analyzersConfigSchema = z
+  .record(z.string(), analyzerOptionsSchema)
+  .optional()
+  .default({})
+  .describe('Per-analyzer configuration overrides')
+
+/**
+ * Complete workspace analyzer configuration schema.
+ */
+export const workspaceAnalyzerConfigSchema = z
+  .object({
+    // Extend from core analyzer config
+    ...analyzerConfigSchema.shape,
+    // Add workspace-specific options
+    ...workspaceOptionsSchema.shape,
+    // Per-analyzer configuration
+    analyzers: analyzersConfigSchema,
+    // Architectural rules
+    architecture: architecturalRulesSchema.optional().describe('Architectural analysis rules'),
+  })
+  .strict()
+
+/**
+ * Schema for the analyzeWorkspace() options parameter.
+ */
+export const analyzeWorkspaceOptionsSchema = z
+  .object({
+    // Include base config options
+    ...analyzerConfigSchema.shape,
+    // Include workspace options
+    ...workspaceOptionsSchema.shape,
+    // API-specific options
+    configPath: z.string().optional().describe('Path to workspace-analyzer.config.ts file'),
+    // onProgress is validated at runtime, not in schema (function types not well-supported in zod v4)
+    analyzers: analyzersConfigSchema,
+    architecture: architecturalRulesSchema.optional(),
+  })
+  .strict()
+
+/**
+ * Inferred types from schemas.
+ */
+export type SeverityInput = z.input<typeof severitySchema>
+export type CategoryInput = z.input<typeof categorySchema>
+export type AnalyzerConfigInput = z.input<typeof analyzerConfigSchema>
+export type WorkspaceOptionsInput = z.input<typeof workspaceOptionsSchema>
+export type WorkspaceAnalyzerConfigInput = z.input<typeof workspaceAnalyzerConfigSchema>
+export type AnalyzeWorkspaceOptionsInput = z.input<typeof analyzeWorkspaceOptionsSchema>
+
+export type SeverityOutput = z.output<typeof severitySchema>
+export type CategoryOutput = z.output<typeof categorySchema>
+export type AnalyzerConfigOutput = z.output<typeof analyzerConfigSchema>
+export type WorkspaceOptionsOutput = z.output<typeof workspaceOptionsSchema>
+export type WorkspaceAnalyzerConfigOutput = z.output<typeof workspaceAnalyzerConfigSchema>
+export type AnalyzeWorkspaceOptionsOutput = z.output<typeof analyzeWorkspaceOptionsSchema>
+
+/**
+ * Validates and parses analyzer configuration.
+ *
+ * @param config - Raw configuration input
+ * @returns Validated and defaulted configuration
+ * @throws {z.ZodError} If validation fails
+ */
+export function parseAnalyzerConfig(config: unknown): AnalyzerConfigOutput {
+  return analyzerConfigSchema.parse(config)
+}
+
+/**
+ * Validates and parses workspace analyzer configuration.
+ *
+ * @param config - Raw configuration input
+ * @returns Validated and defaulted configuration
+ * @throws {z.ZodError} If validation fails
+ */
+export function parseWorkspaceAnalyzerConfig(config: unknown): WorkspaceAnalyzerConfigOutput {
+  return workspaceAnalyzerConfigSchema.parse(config)
+}
+
+/**
+ * Safe parse result type for configuration validation.
+ */
+export type SafeParseResult<T> = {success: true; data: T} | {success: false; error: z.ZodError}
+
+/**
+ * Safely validates configuration without throwing.
+ *
+ * @param config - Raw configuration input
+ * @returns Validation result with success status and data/error
+ */
+export function safeParseWorkspaceAnalyzerConfig(
+  config: unknown,
+): SafeParseResult<WorkspaceAnalyzerConfigOutput> {
+  const result = workspaceAnalyzerConfigSchema.safeParse(config)
+  if (result.success) {
+    return {success: true, data: result.data}
+  }
+  return {success: false, error: result.error}
+}
+
+/**
+ * Validates analyzeWorkspace() options.
+ *
+ * @param options - Raw options input
+ * @returns Validation result with success status and data/error
+ */
+export function safeParseAnalyzeOptions(
+  options: unknown,
+): SafeParseResult<AnalyzeWorkspaceOptionsOutput> {
+  const result = analyzeWorkspaceOptionsSchema.safeParse(options)
+  if (result.success) {
+    return {success: true, data: result.data}
+  }
+  return {success: false, error: result.error}
+}