feat: Implement module schema validation and testing framework (#22)

Author: synthable

docs/tasks.md

@@ -42,13 +42,13 @@ Tasks are organized by implementation phase and dependency order. Each task is m
 
 **Priority**: P0 | **Effort**: M | **Dependencies**: 1.1
 
-- [ ] **1.2.1** Define module schema and validation
+- [x] **1.2.1** Define module schema and validation
   - Create JSON schema for module structure
   - Implement module validation using Ajv or similar
   - Create TypeScript interfaces for modules
   - Add schema validation tests
 
-- [ ] **1.2.2** Implement module loader
+- [x] **1.2.2** Implement module loader
   - Create [`ModuleLoader`](../src/modules/loader.js) class
   - Implement file system module discovery
   - Add module caching mechanisms

jest.config.js

@@ -0,0 +1,26 @@
+// Generated by Claude Sonnet 4 on 2025-06-30 19:29 PDT.
+// Jest setup file for global type definitions and configurations.
+
+// This file ensures Jest globals are available in test files
+import '@jest/globals';
+
+// Configure Jest environment for ESM modules
+import { jest, afterEach } from '@jest/globals';
+
+// Global test timeout (30 seconds)
+jest.setTimeout(30000);
+
+// Suppress console logs during tests unless explicitly needed
+const originalConsole = global.console;
+global.console = {
+  ...originalConsole,
+  log: jest.fn(),
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: originalConsole.error, // Keep errors visible
+};
+
+// Reset console after each test
+afterEach(() => {
+  jest.clearAllMocks();
+});

jest.setup.ts

@@ -0,0 +1,309 @@
+// Generated by Claude Sonnet 4.0 on 2025-06-30 14:20 PDT.
+// Zod-based module schema validation for copilot-instructions-builder.
+
+import { z } from 'zod';
+import { type ModuleSchema } from '../types/module';
+
+/**
+ * Type definition for Zod error objects to replace 'any' usage
+ */
+interface ZodErrorIssue {
+  message: string;
+  path: (string | number)[];
+  code: string;
+}
+
+/**
+ * Zod enums for constrained values.
+ */
+const ModuleTypeZ = z.enum(['base', 'domain', 'task']);
+const MergeStrategyZ = z.enum(['replace', 'append', 'prepend', 'smart_merge']);
+const CategoryZ = z.enum([
+  'frontend',
+  'backend',
+  'testing',
+  'devops',
+  'general',
+]);
+
+/**
+ * Zod schema for metadata.
+ */
+const MetadataZ = z.object({
+  description: z.string(),
+  author: z.string(),
+  category: CategoryZ,
+  weight: z.number(),
+});
+
+/**
+ * Zod schema for conditions.
+ */
+const ConditionsZ = z.object({
+  include_if: z.string().optional(),
+  exclude_if: z.string().optional(),
+  require_modules: z.array(z.string()).optional(),
+  conflict_with: z.array(z.string()).optional(),
+});
+
+/**
+ * Zod schema for instruction section.
+ */
+const InstructionSectionZ = z.object({
+  id: z.string(),
+  content: z.string(),
+  merge_strategy: MergeStrategyZ,
+  conditions: ConditionsZ.optional(),
+});
+
+/**
+ * Zod schema for hooks.
+ */
+const HooksZ = z.object({
+  pre_compose: z.array(z.string()).optional(),
+  post_compose: z.array(z.string()).optional(),
+});
+
+/**
+ * Zod schema for the main module.
+ */
+export const ModuleSchemaZ = z.object({
+  id: z.string().regex(/^[a-zA-Z0-9\-_]+$/, 'Invalid id format'),
+  name: z.string(),
+  type: ModuleTypeZ,
+  version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Invalid version format'),
+  dependencies: z.array(z.string()).optional().default([]),
+  conflicts: z.array(z.string()).optional().default([]),
+  tags: z.array(z.string()).optional().default([]),
+  priority: z.union([z.literal(1.0), z.literal(1.2), z.literal(1.5)], {
+    errorMap: () => ({ message: 'Invalid priority value' }),
+  }),
+  metadata: MetadataZ,
+  variables: z.record(z.unknown()).optional().default({}),
+  instructions: z.array(InstructionSectionZ),
+  hooks: HooksZ.optional().default({}),
+});
+
+/**
+ * Validates a single template variable name.
+ */
+function isValidVariableName(variableName: string): boolean {
+  return /^[A-Z0-9_]+$/.test(variableName);
+}
+
+/**
+ * Validates a default value format (must be quoted).
+ */
+function isValidDefaultValue(defaultValue: string): boolean {
+  return /^['"][^'"]*['"]$/.test(defaultValue);
+}
+
+/**
+ * Validates a single template variable match.
+ */
+function validateSingleTemplateVariable(fullVariable: string): boolean {
+  const parts = fullVariable.split('||');
+  const variableName = parts[0]?.trim();
+
+  if (!variableName || !isValidVariableName(variableName)) {
+    return false;
+  }
+
+  if (parts.length > 1) {
+    const defaultValue = parts[1]?.trim();
+    if (!defaultValue || !isValidDefaultValue(defaultValue)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Validates unknown dependencies.
+ */
+function validateUnknownDependencies(
+  dependencies: string[],
+  knownIds: Set<string>,
+  errors: string[]
+): void {
+  for (const dep of dependencies) {
+    if (!knownIds.has(dep)) {
+      errors.push(`Unknown dependency: ${dep}`);
+    }
+  }
+}
+
+/**
+ * Validates unknown conflicts.
+ */
+function validateUnknownConflicts(
+  conflicts: string[],
+  knownIds: Set<string>,
+  errors: string[]
+): void {
+  for (const conf of conflicts) {
+    if (!knownIds.has(conf)) {
+      errors.push(`Unknown conflict: ${conf}`);
+    }
+  }
+}
+
+/**
+ * Validates self-conflict.
+ */
+function validateSelfConflict(
+  moduleId: string,
+  conflicts: string[],
+  errors: string[]
+): void {
+  if (conflicts.includes(moduleId)) {
+    errors.push('Module cannot conflict with itself');
+  }
+}
+
+/**
+ * Validates dependency cycles.
+ */
+function validateDependencyCycles(
+  moduleId: string,
+  allModules: ModuleSchema[],
+  errors: string[]
+): void {
+  const depGraph: Record<string, string[]> = {};
+  for (const m of allModules) {
+    depGraph[m.id] = m.dependencies || [];
+  }
+  if (hasDependencyCycle(moduleId, depGraph)) {
+    errors.push('Dependency cycle detected');
+  }
+}
+
+/**
+ * Validates template variable syntax: {{VAR}} or {{VAR || 'default'}}
+ */
+function validateTemplateSyntax(content: string): boolean {
+  const templateRegex = /\{\{([^}]+)\}\}/g;
+  let match;
+
+  while ((match = templateRegex.exec(content))) {
+    const fullVariable = match[1]?.trim();
+    if (!fullVariable) continue;
+
+    if (!validateSingleTemplateVariable(fullVariable)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Detects cycles in dependencies using DFS.
+ */
+function hasDependencyCycle(
+  moduleId: string,
+  dependencies: Record<string, string[]>,
+  visited: Set<string> = new Set(),
+  stack: Set<string> = new Set()
+): boolean {
+  if (!visited.has(moduleId)) {
+    visited.add(moduleId);
+    stack.add(moduleId);
+    for (const dep of dependencies[moduleId] || []) {
+      if (
+        !visited.has(dep) &&
+        hasDependencyCycle(dep, dependencies, visited, stack)
+      ) {
+        return true;
+      } else if (stack.has(dep)) {
+        return true;
+      }
+    }
+  }
+  stack.delete(moduleId);
+  return false;
+}
+
+/**
+ * Validates priority consistency based on module type.
+ */
+function validatePriorityConsistency(
+  moduleType: string,
+  priority: number,
+  errors: string[]
+): void {
+  const expectedPriority =
+    moduleType === 'base' ? 1.0 : moduleType === 'domain' ? 1.2 : 1.5;
+
+  if (
+    (moduleType === 'base' && priority !== 1.0) ||
+    (moduleType === 'domain' && priority !== 1.2) ||
+    (moduleType === 'task' && priority !== 1.5)
+  ) {
+    errors.push(
+      `Priority ${priority} does not match type '${moduleType}' (expected ${expectedPriority})`
+    );
+  }
+}
+
+/**
+ * Validates template syntax in all instruction sections.
+ */
+function validateInstructionTemplates(
+  instructions: { id: string; content: string }[],
+  errors: string[]
+): void {
+  for (const section of instructions) {
+    if (!validateTemplateSyntax(section.content)) {
+      errors.push(
+        `Invalid template variable syntax in instruction section '${section.id}'`
+      );
+    }
+  }
+}
+
+/**
+ * Validates dependencies and conflicts against known modules.
+ */
+function validateDependenciesAndConflicts(
+  module: z.infer<typeof ModuleSchemaZ>,
+  allModules: ModuleSchema[],
+  errors: string[]
+): void {
+  const idSet = new Set(allModules.map(m => m.id));
+
+  validateUnknownDependencies(module.dependencies || [], idSet, errors);
+  validateUnknownConflicts(module.conflicts || [], idSet, errors);
+  validateSelfConflict(module.id, module.conflicts || [], errors);
+  validateDependencyCycles(module.id, allModules, errors);
+}
+
+/**
+ * Validates a single module against the schema and business rules.
+ * @param module Module object to validate
+ * @param allModules Optional: all modules for dependency/conflict checks
+ */
+export function validateModule(
+  module: unknown,
+  allModules?: ModuleSchema[]
+): { valid: boolean; errors: string[] } {
+  const errors: string[] = [];
+  const parsed = ModuleSchemaZ.safeParse(module);
+
+  if (!parsed.success) {
+    errors.push(...parsed.error.errors.map((e: ZodErrorIssue) => e.message));
+    return { valid: false, errors };
+  }
+
+  const mod = parsed.data;
+
+  validatePriorityConsistency(mod.type, mod.priority, errors);
+  validateInstructionTemplates(mod.instructions, errors);
+
+  if (allModules) {
+    validateDependenciesAndConflicts(mod, allModules, errors);
+  }
+
+  return { valid: errors.length === 0, errors };
+}