ValidationToolsMixin

Source Code: src/gaia/agents/code/tools/validation_tools.py

Component: ValidationToolsMixin Module: gaia.agents.code.tools.validation_tools Import: from gaia.agents.code.tools.validation_tools import ValidationToolsMixin

Overview

ValidationToolsMixin provides comprehensive testing and validation tools for Next.js applications with Prisma. It includes CRUD API testing, TypeScript validation, file structure validation, and CSS integrity checks. Key Features:

Test CRUD API endpoints using curl
Validate TypeScript compilation
Validate CRUD application structure
Validate CSS files for common issues
Schema-aware test payload generation
Automatic dev server management
Tier 4 error messaging with rule citations

Tool Specifications

1. test_crud_api

Test CRUD API endpoints with automatic payload generation from schema. Parameters:

project_dir (str, required): Path to Next.js project
model_name (str, required): Model name (e.g., “Todo”, “Post”)
port (int, optional): Dev server port (default: 3000)

Returns:

{
    "success": bool,
    "result": {
        "tests_passed": int,
        "tests_failed": int,
        "results": {
            "POST": {"status": int, "pass": bool},
            "GET_LIST": {"status": int, "pass": bool},
            "GET_SINGLE": {"status": int, "pass": bool},
            "PATCH": {"status": int, "pass": bool},
            "DELETE": {"status": int, "pass": bool}
        }
    }
}

Test Sequence:

Ensure dev server is running (start if needed)
Read Prisma schema to get field definitions
Generate test payload from schema fields
POST: Create test record (expect 201)
GET_LIST: List all records (expect 200)
GET_SINGLE: Get created record (expect 200)
PATCH: Update record (expect 200)
DELETE: Delete record (expect 200)
Cleanup: Stop dev server if we started it

2. validate_typescript

Validate TypeScript code with tier 4 error messaging. Parameters:

project_dir (str, required): Path to Next.js project

Returns:

{
    "success": bool,
    "message": str,

    # On failure
    "error": str,
    "errors": str,  # Full tsc output
    "violation": str,  # What was violated
    "rule": str,  # The rule that was violated
    "fix": str,  # How to fix it
    "hint": str
}

Detected Violations:

Missing type imports
Missing Prisma singleton
Prisma types not generated
Direct prisma import in client component

Example Error Response:

{
    "success": False,
    "error": "TypeScript validation failed",
    "errors": "src/app/todos/page.tsx(5,10): error TS2304: Cannot find name 'Todo'.",
    "violation": "Missing type import",
    "rule": "Client components must use: import type { X } from '@prisma/client'",
    "fix": "Add the missing type import at the top of the file",
    "hint": "Fix the type errors listed above, then run validate_typescript again"
}

3. validate_crud_structure

Validate that all required CRUD files exist. Parameters:

project_dir (str, required): Path to Next.js project
resource_name (str, required): Resource name (e.g., “todo”)

Returns:

{
    "success": bool,
    "missing_files": [
        {
            "description": str,
            "path": str,
            "create_with": str  # Tool command to create
        }
    ],
    "existing_files": List[str],
    "details": str,  # Human-readable report
    "hint": str
}

Checked Files:

List page: src/app/{resource_plural}/page.tsx
New page: src/app/{resource_plural}/new/page.tsx
Detail page: src/app/{resource_plural}/[id]/page.tsx
Form component: src/components/{Resource}Form.tsx
Actions component: src/components/{Resource}Actions.tsx
Collection API: src/app/api/{resource_plural}/route.ts
Item API: src/app/api/{resource_plural}/[id]/route.ts

4. validate_styles

Validate CSS files and design system consistency. Parameters:

project_dir (str, required): Path to Next.js project
resource_name (str, optional): Resource name for component checks

Returns:

{
    "success": bool,
    "is_valid": bool,
    "errors": List[str],  # CRITICAL errors
    "warnings": List[str],  # Non-blocking warnings
    "files_checked": List[str],
    "hint": str
}

Validates:

CSS files contain valid CSS (not TypeScript) - CRITICAL
globals.css has Tailwind directives
layout.tsx imports globals.css
Balanced braces in CSS files

TypeScript Detection Patterns:

[
    r"^\s*import\s+.*from",  # import statement
    r"^\s*export\s+",  # export statement
    r'"use client"|\'use client\'',  # React directive
    r"^\s*interface\s+\w+",  # TypeScript interface
    r"^\s*type\s+\w+\s*=",  # Type alias
    r"^\s*const\s+\w+\s*[=:]",  # const declaration
    r"<[A-Z][a-zA-Z]*[\s/>]",  # JSX component
    r"useState|useEffect|useRouter",  # React hooks
]

Helper Functions

generate_test_payload

Generate test data from Prisma field definitions. Parameters:

fields (Dict[str, str]): Field names to types

Returns:

Dict[str, Any]  # Test values for each field

Type Mappings:

{
    "String" | "Text": "Test Field Name",
    "Int" | "Number": 42,
    "Float": 3.14,
    "Boolean": True (for active/enabled) | False,
    "DateTime": "2025-01-01T00:00:00.000Z"
}

_get_create_command

Generate tool command to create missing CRUD file. Parameters:

description (str): File description
resource_name (str): Resource name

Returns:

str  # Tool command (e.g., 'manage_react_component(variant="form", ...)')

Usage Examples

Example 1: Test CRUD API

from gaia import CodeAgent

agent = CodeAgent()

# Test Todo CRUD API
result = agent.test_crud_api(
    project_dir="/path/to/nextjs-app",
    model_name="Todo",
    port=3000
)

if result["success"]:
    print(f"✓ All {result['result']['tests_passed']} tests passed!")
else:
    print(f"✗ {result['result']['tests_failed']} tests failed:")
    for test, outcome in result["result"]["results"].items():
        if not outcome["pass"]:
            print(f"  {test}: HTTP {outcome['status']}")

Example 2: Validate TypeScript

result = agent.validate_typescript(
    project_dir="/path/to/nextjs-app"
)

if result["success"]:
    print("✓ TypeScript validation passed")
else:
    print(f"✗ {result['error']}")
    print(f"\nViolation: {result.get('violation', 'Unknown')}")
    print(f"Rule: {result.get('rule', 'N/A')}")
    print(f"Fix: {result.get('fix', 'See errors above')}")
    print(f"\nErrors:\n{result.get('errors', '')}")

Example 3: Validate CRUD Structure

result = agent.validate_crud_structure(
    project_dir="/path/to/nextjs-app",
    resource_name="todo"
)

if result["success"]:
    print("✓ Complete CRUD structure validated")
else:
    print("✗ Missing files:")
    for missing in result["missing_files"]:
        print(f"\n  {missing['description']}")
        print(f"  Path: {missing['path']}")
        print(f"  Create: {missing['create_with']}")

Example 4: Validate Styles

result = agent.validate_styles(
    project_dir="/path/to/nextjs-app",
    resource_name="todo"
)

if result["is_valid"]:
    print("✓ Styling validated successfully")
    if result.get("warnings"):
        print(f"  Warnings: {len(result['warnings'])}")
else:
    print("✗ Style validation failed:")
    for error in result["errors"]:
        print(f"  - {error}")
    print(f"\nHint: {result.get('hint', '')}")

Testing Requirements

File: tests/agents/code/test_validation_tools.py

def test_generate_test_payload():
    """Test payload generation from schema fields."""
    fields = {
        "title": "String",
        "count": "Int",
        "price": "Float",
        "active": "Boolean",
        "createdAt": "DateTime"
    }

    payload = generate_test_payload(fields)

    assert isinstance(payload["title"], str)
    assert isinstance(payload["count"], int)
    assert isinstance(payload["price"], float)
    assert isinstance(payload["active"], bool)
    assert isinstance(payload["createdAt"], str)

def test_validate_crud_structure():
    """Test CRUD structure validation."""
    # Create temporary project with incomplete structure
    result = validate_crud_structure(project_dir, "todo")

    assert not result["success"]
    assert len(result["missing_files"]) > 0
    assert "create_with" in result["missing_files"][0]

def test_validate_styles_detects_typescript():
    """Test TypeScript detection in CSS files."""
    # Create CSS file with TypeScript content
    css_file = project_dir / "src/app/globals.css"
    css_file.write_text('import React from "react"')

    result = validate_styles(str(project_dir))

    assert not result["is_valid"]
    assert any("TypeScript" in error for error in result["errors"])

Dependencies

import json
import logging
import re
import subprocess
import time
from pathlib import Path
from typing import Any, Dict

from gaia.agents.base.tools import tool
from gaia.agents.code.prompts.code_patterns import pluralize
from gaia.agents.code.tools.cli_tools import is_port_available
from gaia.agents.code.tools.web_dev_tools import read_prisma_model

Integration with Other Mixins

Requires CLIToolsMixin

_run_foreground_command: Execute curl commands
_run_background_command: Start dev server
_stop_process: Stop dev server

Requires WebToolsMixin

read_prisma_model: Read schema for field definitions

ValidationToolsMixin Technical Specification

Core Framework

SDKs

Infrastructure

Code Infrastructure

Tool Mixins

Packaging

Agents & Apps

ValidationToolsMixin

Overview

Tool Specifications

1. test_crud_api

2. validate_typescript

3. validate_crud_structure

4. validate_styles

Helper Functions

generate_test_payload

_get_create_command

Usage Examples

Example 1: Test CRUD API

Example 2: Validate TypeScript

Example 3: Validate CRUD Structure

Example 4: Validate Styles

Testing Requirements

Dependencies

Integration with Other Mixins

Requires CLIToolsMixin

Requires WebToolsMixin

Core Framework

SDKs

Infrastructure

Code Infrastructure

Tool Mixins

Packaging

Agents & Apps

​Overview

​Tool Specifications

​1. test_crud_api

​2. validate_typescript

​3. validate_crud_structure

​4. validate_styles

​Helper Functions

​generate_test_payload

​_get_create_command

​Usage Examples

​Example 1: Test CRUD API

​Example 2: Validate TypeScript

​Example 3: Validate CRUD Structure

​Example 4: Validate Styles

​Testing Requirements

​Dependencies

​Integration with Other Mixins

​Requires CLIToolsMixin

​Requires WebToolsMixin

Overview

Tool Specifications

1. test_crud_api

2. validate_typescript

3. validate_crud_structure

4. validate_styles

Helper Functions

generate_test_payload

_get_create_command

Usage Examples

Example 1: Test CRUD API

Example 2: Validate TypeScript

Example 3: Validate CRUD Structure

Example 4: Validate Styles

Testing Requirements

Dependencies

Integration with Other Mixins

Requires CLIToolsMixin

Requires WebToolsMixin