feat: add validate-files command for PR validation

Add new `validate-files` command to enable efficient validation of individual
room files without requiring full mapdb reconstruction. This is essential
for GitHub Actions PR validation workflows.

Features:
- Validate specific room.json files by path
- Support both GitRoom format and direct room format
- JSON output option for CI integration (--json flag)
- Detailed error reporting with file paths and room info
- Comprehensive test coverage

Usage:
  bun run mapdb validate-files gs/rooms/123/room.json gs/rooms/456/room.json
  bun run mapdb validate-files --json changed-files.txt

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: ondreian

mapdb/mapdb.ts

@@ -73,6 +73,42 @@ program.command("validate")
       process.exit(0)
     })
 
+program.command("validate-files")
+  .alias("vf")
+  .description("validate specific room files")
+  .option("--dr", "run in dragonrealms mode", false)
+  .option("--json", "output errors in JSON format", false)
+  .argument("<files...>", "room.json file paths to validate")
+  .action(async (files: string[], args: {dr: boolean, json: boolean}) => {
+    const then = performance.now()
+    const spinner = ora()
+    
+    spinner.start(`validating ${files.length} room files...`)
+    
+    try {
+      const results = await Tasks.validateFiles({files, json: args.json})
+      const runtime = Math.round(performance.now() - then)
+      
+      if (results.errors.length === 0) {
+        spinner.succeed(`[${runtime}ms] validated ${results.validFiles} files`)
+        process.exit(0)
+      } else {
+        spinner.fail(`[${runtime}ms] found ${results.errors.length} validation errors`)
+        
+        if (args.json) {
+          console.log(JSON.stringify(results, null, 2))
+        } else {
+          console.table(results.errors)
+        }
+        process.exit(1)
+      }
+    } catch (error: any) {
+      const runtime = Math.round(performance.now() - then)
+      spinner.fail(`[${runtime}ms] ${error.message}`)
+      process.exit(1)
+    }
+  })
+
 program.command("reconstruct")
   .alias("r")
   .description("reconstruct a mapdb.json file from git directory structure")

mapdb/tasks/index.ts

@@ -2,4 +2,5 @@ import { download } from "./download"
 import { validate } from "./validate"
 import { git } from "./git"
 import { reconstruct } from "./reconstruct"
-export { download, validate, git, reconstruct }
+import { validateFiles } from "./validate-files"
+export { download, validate, git, reconstruct, validateFiles }

mapdb/tasks/validate-files.ts

@@ -0,0 +1,77 @@
+import * as fs from "node:fs/promises"
+import { Room } from "../room/room"
+import { fromError } from 'zod-validation-error'
+
+export interface ValidateFilesConfig {
+  files: string[];
+  json: boolean;
+}
+
+export interface FileValidationError {
+  file: string;
+  id?: number;
+  title?: string;
+  error: string;
+}
+
+export interface ValidateFilesResult {
+  validFiles: number;
+  errors: FileValidationError[];
+  files: string[];
+}
+
+export async function validateFiles(config: ValidateFilesConfig): Promise<ValidateFilesResult> {
+  const { files } = config
+  const errors: FileValidationError[] = []
+  let validFiles = 0
+
+  for (const file of files) {
+    try {
+      // Read the git room file
+      const fileContent = await fs.readFile(file, 'utf-8')
+      const gitRoom = JSON.parse(fileContent)
+      
+      // Extract room data - handle both GitRoom format and direct room format
+      const roomData = gitRoom.room || gitRoom
+      
+      // Validate using Room class
+      Room.validate(roomData)
+      validFiles++
+      
+    } catch (error: any) {
+      let errorMessage = error.message
+      let roomId: number | undefined
+      let roomTitle: string | undefined
+      
+      // Try to extract room info even if validation failed
+      try {
+        const fileContent = await fs.readFile(file, 'utf-8')
+        const gitRoom = JSON.parse(fileContent)
+        const roomData = gitRoom.room || gitRoom
+        roomId = roomData.id
+        roomTitle = roomData.title?.[0]
+      } catch {
+        // Ignore errors when trying to extract room info
+      }
+      
+      // If it's a Zod validation error, make it more readable
+      if (error.name === 'ZodError') {
+        const humanized = fromError(error)
+        errorMessage = humanized.toString()
+      }
+      
+      errors.push({
+        file,
+        id: roomId,
+        title: roomTitle,
+        error: errorMessage
+      })
+    }
+  }
+
+  return {
+    validFiles,
+    errors,
+    files
+  }
+}

test/validate-files.spec.ts

@@ -0,0 +1,130 @@
+import { expect, test, beforeAll, afterAll } from "bun:test"
+import * as Tasks from "../mapdb/tasks"
+import * as fs from "node:fs/promises"
+import * as path from "path"
+
+test("validateFiles can validate valid room files", async () => {
+  const testDir = "/tmp/test-validate-files"
+  const validRoomFile = path.join(testDir, "valid-room.json")
+  
+  try {
+    // Clean up any existing test data
+    await fs.rm(testDir, { recursive: true, force: true })
+    await fs.mkdir(testDir, { recursive: true })
+
+    // Create a valid room file in GitRoom format
+    const validRoom = {
+      checksum: "abc123",
+      room: {
+        id: 123,
+        title: ["Test Room"],
+        description: ["A test room for validation."],
+        terrain: "rough",
+        wayto: {},
+        timeto: {},
+        location: "test"
+      }
+    }
+
+    await fs.writeFile(validRoomFile, JSON.stringify(validRoom, null, 2))
+
+    // Test validation
+    const results = await Tasks.validateFiles({
+      files: [validRoomFile],
+      json: false
+    })
+
+    expect(results.validFiles).toBe(1)
+    expect(results.errors.length).toBe(0)
+    expect(results.files).toEqual([validRoomFile])
+
+  } finally {
+    // Clean up test files
+    await fs.rm(testDir, { recursive: true, force: true })
+  }
+})
+
+test("validateFiles can detect invalid room files", async () => {
+  const testDir = "/tmp/test-validate-files-invalid"
+  const invalidRoomFile = path.join(testDir, "invalid-room.json")
+  
+  try {
+    // Clean up any existing test data
+    await fs.rm(testDir, { recursive: true, force: true })
+    await fs.mkdir(testDir, { recursive: true })
+
+    // Create an invalid room file (missing required fields)
+    const invalidRoom = {
+      checksum: "abc123",
+      room: {
+        id: "invalid", // Should be number
+        title: ["Test Room"],
+        // Missing wayto, timeto (required fields)
+      }
+    }
+
+    await fs.writeFile(invalidRoomFile, JSON.stringify(invalidRoom, null, 2))
+
+    // Test validation
+    const results = await Tasks.validateFiles({
+      files: [invalidRoomFile],
+      json: true
+    })
+
+    expect(results.validFiles).toBe(0)
+    expect(results.errors.length).toBe(1)
+    expect(results.errors[0].file).toBe(invalidRoomFile)
+    expect(results.errors[0].id).toBe("invalid")
+    expect(results.errors[0].error).toContain("Expected number, received string")
+
+  } finally {
+    // Clean up test files
+    await fs.rm(testDir, { recursive: true, force: true })
+  }
+})
+
+test("validateFiles can handle mixed valid and invalid files", async () => {
+  const testDir = "/tmp/test-validate-files-mixed"
+  const validFile = path.join(testDir, "valid.json")
+  const invalidFile = path.join(testDir, "invalid.json")
+  
+  try {
+    await fs.rm(testDir, { recursive: true, force: true })
+    await fs.mkdir(testDir, { recursive: true })
+
+    // Create valid room
+    const validRoom = {
+      checksum: "abc123",
+      room: {
+        id: 456,
+        title: ["Valid Room"],
+        description: ["A valid room."],
+        wayto: {},
+        timeto: {}
+      }
+    }
+
+    // Create invalid room
+    const invalidRoom = {
+      room: {
+        id: 789,
+        // Missing wayto, timeto
+      }
+    }
+
+    await fs.writeFile(validFile, JSON.stringify(validRoom, null, 2))
+    await fs.writeFile(invalidFile, JSON.stringify(invalidRoom, null, 2))
+
+    const results = await Tasks.validateFiles({
+      files: [validFile, invalidFile],
+      json: false
+    })
+
+    expect(results.validFiles).toBe(1)
+    expect(results.errors.length).toBe(1)
+    expect(results.files.length).toBe(2)
+
+  } finally {
+    await fs.rm(testDir, { recursive: true, force: true })
+  }
+})