@mandujs/core 0.8.2 → 0.9.0

package/src/watcher/rules.ts

@@ -0,0 +1,248 @@
+/**
+ * Brain v0.1 - Watch Architecture Rules
+ *
+ * 5 MVP rules that catch the most common mistakes.
+ * Rules only warn - they never block operations.
+ */
+
+import type { ArchRule, WatchWarning } from "../brain/types";
+import path from "path";
+import fs from "fs/promises";
+
+/**
+ * The 5 MVP Architecture Rules
+ *
+ * These rules cover the most frequent mistakes in Mandu projects:
+ * 1. Direct modification of generated files
+ * 2. Slot files in wrong locations
+ * 3. Slot file naming convention
+ * 4. Contract file naming convention
+ * 5. Forbidden imports in generated files
+ */
+export const MVP_RULES: ArchRule[] = [
+  {
+    id: "GENERATED_DIRECT_EDIT",
+    name: "Generated Direct Edit",
+    description: "Generated 파일은 직접 수정하면 안 됩니다",
+    pattern: "generated/**",
+    action: "warn",
+    message: "Generated 파일이 직접 수정되었습니다. 이 파일은 `mandu generate`로 재생성됩니다.",
+  },
+  {
+    id: "WRONG_SLOT_LOCATION",
+    name: "Wrong Slot Location",
+    description: "Slot 파일은 spec/slots/ 디렉토리에 있어야 합니다",
+    pattern: "src/**/*.slot.ts",
+    action: "warn",
+    message: "Slot 파일이 잘못된 위치에 있습니다. spec/slots/ 디렉토리로 이동하세요.",
+  },
+  {
+    id: "SLOT_NAMING",
+    name: "Slot Naming Convention",
+    description: "Slot 파일은 .slot.ts로 끝나야 합니다",
+    pattern: "spec/slots/*.ts",
+    action: "warn",
+    message: "Slot 파일명이 .slot.ts로 끝나야 합니다.",
+    mustEndWith: ".slot.ts",
+  },
+  {
+    id: "CONTRACT_NAMING",
+    name: "Contract Naming Convention",
+    description: "Contract 파일은 .contract.ts로 끝나야 합니다",
+    pattern: "spec/contracts/*.ts",
+    action: "warn",
+    message: "Contract 파일명이 .contract.ts로 끝나야 합니다.",
+    mustEndWith: ".contract.ts",
+  },
+  {
+    id: "FORBIDDEN_IMPORT",
+    name: "Forbidden Import in Generated",
+    description: "Generated 파일에서 금지된 모듈 import",
+    pattern: "generated/**",
+    action: "warn",
+    message: "Generated 파일에서 금지된 모듈이 import되었습니다.",
+    forbiddenImports: ["fs", "child_process", "cluster", "worker_threads"],
+  },
+];
+
+/**
+ * Get all rules as a map by ID
+ */
+export function getRulesMap(): Map<string, ArchRule> {
+  const map = new Map<string, ArchRule>();
+  for (const rule of MVP_RULES) {
+    map.set(rule.id, rule);
+  }
+  return map;
+}
+
+/**
+ * Simple glob pattern matching
+ *
+ * Supports:
+ * - ** for any path segment(s)
+ * - * for any characters in a single segment
+ */
+export function matchGlob(pattern: string, filePath: string): boolean {
+  // Normalize path separators
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  const normalizedPattern = pattern.replace(/\\/g, "/");
+
+  // Convert glob to regex
+  const regexPattern = normalizedPattern
+    .replace(/\*\*/g, "<<DOUBLESTAR>>")
+    .replace(/\*/g, "[^/]*")
+    .replace(/<<DOUBLESTAR>>/g, ".*")
+    .replace(/\//g, "\\/");
+
+  const regex = new RegExp(`^${regexPattern}$`);
+  return regex.test(normalizedPath);
+}
+
+/**
+ * Check if a file path matches any rule
+ */
+export function matchRules(filePath: string): ArchRule[] {
+  const matched: ArchRule[] = [];
+
+  for (const rule of MVP_RULES) {
+    if (matchGlob(rule.pattern, filePath)) {
+      matched.push(rule);
+    }
+  }
+
+  return matched;
+}
+
+/**
+ * Check file naming convention
+ */
+export function checkNamingConvention(
+  filePath: string,
+  rule: ArchRule
+): boolean {
+  if (!rule.mustEndWith) return true;
+
+  const fileName = path.basename(filePath);
+  return fileName.endsWith(rule.mustEndWith);
+}
+
+/**
+ * Check for forbidden imports in file content
+ */
+export async function checkForbiddenImports(
+  filePath: string,
+  content: string,
+  rule: ArchRule
+): Promise<string[]> {
+  if (!rule.forbiddenImports || rule.forbiddenImports.length === 0) {
+    return [];
+  }
+
+  const found: string[] = [];
+
+  for (const forbidden of rule.forbiddenImports) {
+    const importRegex = new RegExp(
+      `import\\s+.*from\\s+['"]${forbidden}['"]|require\\s*\\(\\s*['"]${forbidden}['"]\\s*\\)`,
+      "g"
+    );
+
+    if (importRegex.test(content)) {
+      found.push(forbidden);
+    }
+  }
+
+  return found;
+}
+
+/**
+ * Validate a file against all applicable rules
+ */
+export async function validateFile(
+  filePath: string,
+  event: "create" | "modify" | "delete",
+  rootDir: string
+): Promise<WatchWarning[]> {
+  const warnings: WatchWarning[] = [];
+
+  // Get relative path from root
+  const relativePath = path.relative(rootDir, filePath).replace(/\\/g, "/");
+
+  // Find matching rules
+  const matchedRules = matchRules(relativePath);
+
+  for (const rule of matchedRules) {
+    // Skip delete events for most rules
+    if (event === "delete" && rule.id !== "GENERATED_DIRECT_EDIT") {
+      continue;
+    }
+
+    // Check naming convention
+    if (rule.mustEndWith && !checkNamingConvention(relativePath, rule)) {
+      warnings.push({
+        ruleId: rule.id,
+        file: relativePath,
+        message: rule.message,
+        timestamp: new Date(),
+        event,
+      });
+      continue;
+    }
+
+    // Check forbidden imports (only for modify/create)
+    if (
+      rule.forbiddenImports &&
+      rule.forbiddenImports.length > 0 &&
+      event !== "delete"
+    ) {
+      try {
+        const content = await fs.readFile(filePath, "utf-8");
+        const forbidden = await checkForbiddenImports(
+          relativePath,
+          content,
+          rule
+        );
+
+        if (forbidden.length > 0) {
+          warnings.push({
+            ruleId: rule.id,
+            file: relativePath,
+            message: `${rule.message} (${forbidden.join(", ")})`,
+            timestamp: new Date(),
+            event,
+          });
+        }
+      } catch {
+        // File might not exist or be readable
+      }
+      continue;
+    }
+
+    // Default: generate warning for pattern match
+    if (rule.id === "GENERATED_DIRECT_EDIT" || rule.id === "WRONG_SLOT_LOCATION") {
+      warnings.push({
+        ruleId: rule.id,
+        file: relativePath,
+        message: rule.message,
+        timestamp: new Date(),
+        event,
+      });
+    }
+  }
+
+  return warnings;
+}
+
+/**
+ * Get rule by ID
+ */
+export function getRule(ruleId: string): ArchRule | undefined {
+  return MVP_RULES.find((r) => r.id === ruleId);
+}
+
+/**
+ * Get all rules
+ */
+export function getAllRules(): readonly ArchRule[] {
+  return MVP_RULES;
+}

package/src/watcher/watcher.ts

@@ -0,0 +1,330 @@
+/**
+ * Brain v0.1 - File Watcher
+ *
+ * Watches for file changes and triggers warnings (no blocking).
+ * Uses native file system watching for efficiency.
+ */
+
+import type {
+  WatchStatus,
+  WatchWarning,
+  WatchEventHandler,
+} from "../brain/types";
+import { validateFile, MVP_RULES } from "./rules";
+import path from "path";
+import fs from "fs";
+
+/**
+ * Watcher configuration
+ */
+export interface WatcherConfig {
+  /** Root directory to watch */
+  rootDir: string;
+  /** Debounce delay in ms (default: 300) */
+  debounceMs?: number;
+  /** Extra commands to run on violations */
+  extraCommands?: string[];
+  /** Directories to ignore */
+  ignoreDirs?: string[];
+  /** File extensions to watch */
+  watchExtensions?: string[];
+}
+
+/**
+ * Default watcher configuration
+ */
+const DEFAULT_CONFIG: Partial<WatcherConfig> = {
+  debounceMs: 300,
+  ignoreDirs: ["node_modules", ".git", "dist", ".next", ".turbo"],
+  watchExtensions: [".ts", ".tsx", ".js", ".jsx", ".json"],
+};
+
+/**
+ * File Watcher class
+ *
+ * Monitors file changes and emits warnings based on architecture rules.
+ * Never blocks operations - only warns.
+ */
+export class FileWatcher {
+  private config: WatcherConfig;
+  private watchers: Map<string, fs.FSWatcher> = new Map();
+  private handlers: Set<WatchEventHandler> = new Set();
+  private recentWarnings: WatchWarning[] = [];
+  private debounceTimers: Map<string, NodeJS.Timeout> = new Map();
+  private _active: boolean = false;
+  private _startedAt: Date | null = null;
+  private _fileCount: number = 0;
+
+  constructor(config: WatcherConfig) {
+    this.config = {
+      ...DEFAULT_CONFIG,
+      ...config,
+    };
+  }
+
+  /**
+   * Start watching
+   */
+  async start(): Promise<void> {
+    if (this._active) {
+      return;
+    }
+
+    const { rootDir } = this.config;
+
+    // Verify root directory exists
+    if (!fs.existsSync(rootDir)) {
+      throw new Error(`Root directory does not exist: ${rootDir}`);
+    }
+
+    // Watch the root directory and subdirectories
+    await this.watchDirectory(rootDir);
+
+    this._active = true;
+    this._startedAt = new Date();
+  }
+
+  /**
+   * Stop watching
+   */
+  stop(): void {
+    if (!this._active) {
+      return;
+    }
+
+    // Close all watchers
+    for (const [, watcher] of this.watchers) {
+      watcher.close();
+    }
+    this.watchers.clear();
+
+    // Clear debounce timers
+    for (const [, timer] of this.debounceTimers) {
+      clearTimeout(timer);
+    }
+    this.debounceTimers.clear();
+
+    this._active = false;
+    this._fileCount = 0;
+  }
+
+  /**
+   * Add an event handler
+   */
+  onWarning(handler: WatchEventHandler): () => void {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+
+  /**
+   * Get current status
+   */
+  getStatus(): WatchStatus {
+    return {
+      active: this._active,
+      rootDir: this._active ? this.config.rootDir : null,
+      fileCount: this._fileCount,
+      recentWarnings: this.recentWarnings.slice(-20), // Last 20 warnings
+      startedAt: this._startedAt,
+    };
+  }
+
+  /**
+   * Get recent warnings
+   */
+  getRecentWarnings(limit: number = 20): WatchWarning[] {
+    return this.recentWarnings.slice(-limit);
+  }
+
+  /**
+   * Clear recent warnings
+   */
+  clearWarnings(): void {
+    this.recentWarnings = [];
+  }
+
+  /**
+   * Watch a directory recursively
+   */
+  private async watchDirectory(dir: string): Promise<void> {
+    const { ignoreDirs } = this.config;
+
+    // Skip ignored directories
+    const dirName = path.basename(dir);
+    if (ignoreDirs?.includes(dirName)) {
+      return;
+    }
+
+    try {
+      // Watch this directory
+      const watcher = fs.watch(dir, (eventType, filename) => {
+        if (filename) {
+          this.handleFileEvent(eventType, path.join(dir, filename));
+        }
+      });
+
+      watcher.on("error", (error) => {
+        console.error(`[Watch] Error watching ${dir}:`, error.message);
+      });
+
+      this.watchers.set(dir, watcher);
+      this._fileCount++;
+
+      // Recursively watch subdirectories
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (entry.isDirectory() && !ignoreDirs?.includes(entry.name)) {
+          await this.watchDirectory(path.join(dir, entry.name));
+        }
+      }
+    } catch (error) {
+      // Directory might not exist or be accessible
+      console.error(
+        `[Watch] Failed to watch ${dir}:`,
+        error instanceof Error ? error.message : error
+      );
+    }
+  }
+
+  /**
+   * Handle a file system event
+   */
+  private handleFileEvent(eventType: string, filePath: string): void {
+    const { debounceMs, watchExtensions } = this.config;
+
+    // Check file extension
+    const ext = path.extname(filePath);
+    if (watchExtensions && !watchExtensions.includes(ext)) {
+      return;
+    }
+
+    // Debounce events for the same file
+    const existingTimer = this.debounceTimers.get(filePath);
+    if (existingTimer) {
+      clearTimeout(existingTimer);
+    }
+
+    const timer = setTimeout(() => {
+      this.debounceTimers.delete(filePath);
+      this.processFileEvent(eventType, filePath);
+    }, debounceMs);
+
+    this.debounceTimers.set(filePath, timer);
+  }
+
+  /**
+   * Process a debounced file event
+   */
+  private async processFileEvent(
+    eventType: string,
+    filePath: string
+  ): Promise<void> {
+    const { rootDir } = this.config;
+
+    // Determine event type
+    let event: "create" | "modify" | "delete";
+
+    if (eventType === "rename") {
+      // Check if file exists to determine create vs delete
+      event = fs.existsSync(filePath) ? "create" : "delete";
+    } else {
+      event = "modify";
+    }
+
+    // Validate file against rules
+    try {
+      const warnings = await validateFile(filePath, event, rootDir);
+
+      for (const warning of warnings) {
+        this.emitWarning(warning);
+      }
+    } catch (error) {
+      console.error(
+        `[Watch] Error validating ${filePath}:`,
+        error instanceof Error ? error.message : error
+      );
+    }
+  }
+
+  /**
+   * Emit a warning to all handlers
+   */
+  private emitWarning(warning: WatchWarning): void {
+    // Add to recent warnings
+    this.recentWarnings.push(warning);
+
+    // Keep only last 100 warnings
+    if (this.recentWarnings.length > 100) {
+      this.recentWarnings = this.recentWarnings.slice(-100);
+    }
+
+    // Notify all handlers
+    for (const handler of this.handlers) {
+      try {
+        handler(warning);
+      } catch (error) {
+        console.error(
+          "[Watch] Handler error:",
+          error instanceof Error ? error.message : error
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Create a file watcher with default console output
+ */
+export function createWatcher(config: WatcherConfig): FileWatcher {
+  const watcher = new FileWatcher(config);
+
+  // Add default console handler
+  watcher.onWarning((warning) => {
+    const icon = warning.event === "delete" ? "🗑️" : "⚠️";
+    console.log(
+      `${icon} [${warning.ruleId}] ${warning.file}\n   ${warning.message}`
+    );
+  });
+
+  return watcher;
+}
+
+/**
+ * Global watcher instance
+ */
+let globalWatcher: FileWatcher | null = null;
+
+/**
+ * Get or create the global watcher
+ */
+export function getWatcher(config?: WatcherConfig): FileWatcher | null {
+  if (!globalWatcher && config) {
+    globalWatcher = new FileWatcher(config);
+  }
+  return globalWatcher;
+}
+
+/**
+ * Start the global watcher
+ */
+export async function startWatcher(config: WatcherConfig): Promise<FileWatcher> {
+  if (globalWatcher) {
+    globalWatcher.stop();
+  }
+
+  globalWatcher = createWatcher(config);
+  await globalWatcher.start();
+
+  return globalWatcher;
+}
+
+/**
+ * Stop the global watcher
+ */
+export function stopWatcher(): void {
+  if (globalWatcher) {
+    globalWatcher.stop();
+    globalWatcher = null;
+  }
+}