First Project: VIBEE Spec to Code

15 минут для создания первого VIBEE проекта от начала до конца

VIBEE Development Workflow

Цель этого туториала

Создать полноценный VIBEE спецификацию, сгенерировать код, и запустить тесты.

Что вы создадите:

• Модуль для работы с todo-задачами
• Типы: Task, TaskList
• Функции: add, complete, list

---

Step 1: Create Spec File

# Create specs directory
mkdir -p specs/tri

# Create todo module spec
cat > specs/tri/todo.vibee << 'EOF'
name: todo_manager
version: "1.0.0"
language: zig
module: todo_manager

types:
  Task:
    fields:
      id: Int
      title: String
      completed: Bool

  TaskList:
    fields:
      tasks: List<Task>
      count: Int

behaviors:
  - name: create_task
    given: a title string
    when: create_task is called
    then: returns a new Task with unique id

  - name: add_task
    given: a TaskList and a Task
    when: add_task is called
    then: adds the task to the list

  - name: complete_task
    given: a TaskList and task id
    when: complete_task is called
    then: marks the task as completed

  - name: list_tasks
    given: a TaskList
    when: list_tasks is called
    then: returns all tasks with their status
EOF

Terminal output:

$ mkdir -p specs/tri
$ cat > specs/tri/todo.vibee << 'EOF'
...
$ wc -l specs/tri/todo.vibee
     34 specs/tri/todo.vibee

---

Step 2: Generate Code

# Generate Zig code from spec
./zig-out/bin/tri gen specs/tri/todo.vibee

# Check generated code
cat trinity/output/todo_manager.zig

Terminal output:

$ ./zig-out/bin/tri gen specs/tri/todo.vibee

[φ] VIBEE Compiler v0.2.0
═════════════════════════════════════

📖 Reading spec: specs/tri/todo.vibee
   ✓ Parsed 2 types, 4 behaviors

⚙️  Generating Zig code...
   Types:
      • Task (id, title, completed)
      • TaskList (tasks, count)
   Behaviors:
      • create_task(title) -> Task
      • add_task(list, task)
      • complete_task(list, id) -> bool
      • list_tasks(list) -> []Task

   ✓ Writing: trinity/output/todo_manager.zig
   ✓ Generated 89 lines of code

🎉 Code generation complete!

---

Step 3: Review Generated Code

The generated code includes:

//! Autogenerated from todo_manager.vibee
//! Do not edit directly - modify the .vibee spec instead

const std = @import("std");

pub const Task = struct {
    id: i64,
    title: []const u8,
    completed: bool,
};

pub const TaskList = struct {
    tasks: std.ArrayList(Task),
    count: usize,

    pub fn init(allocator: std.mem.Allocator) TaskList {
        return .{
            .tasks = std.ArrayList(Task).init(allocator),
            .count = 0,
        };
    }
};

pub fn createTask(allocator: std.mem.Allocator, title: []const u8) !Task {
    return .{
        .id = std.time.timestamp(),
        .title = try allocator.dupe(u8, title),
        .completed = false,
    };
}

pub fn addTask(list: *TaskList, task: Task) !void {
    try list.tasks.append(task);
    list.count += 1;
}

pub fn completeTask(list: *TaskList, task_id: i64) bool {
    for (list.tasks.items) |*task| {
        if (task.id == task_id) {
            task.completed = true;
            return true;
        }
    }
    return false;
}

pub fn listTasks(list: *TaskList) []const Task {
    return list.tasks.items;
}

---

Step 4: Create Test

cat > trinity/output/todo_test.zig << 'EOF'
const std = @import("std");
const todo = @import("todo_manager.zig");

test "create task" {
    const allocator = std.testing.allocator;
    const task = try todo.createTask(allocator, "Learn VIBEE");
    defer allocator.free(task.title);

    try std.testing.expectEqual(@as(i64, 0), task.id); // Will be timestamp
    try std.testing.expectEqual(false, task.completed);
}

test "add and complete task" {
    const allocator = std.testing.allocator;
    var list = todo.TaskList.init(allocator);
    defer list.tasks.deinit();

    const task = try todo.createTask(allocator, "Learn Trinity");
    defer allocator.free(task.title);

    try todo.addTask(&list, task);
    try std.testing.expectEqual(@as(usize, 1), list.count);

    const found = todo.completeTask(&list, task.id);
    try std.testing.expect(found);
}
EOF

---

Step 5: Run Tests

# Run the tests
zig test trinity/output/todo_test.zig

Terminal output:

$ zig test trinity/output/todo_test.zig

Test [1/2] create task... OK
Test [2/2] add and complete task... OK

All 2 tests passed!
0 errors, 0 warnings.

╔═══════════════════════════════════════════════════════════╗
║           ✓ VIBEE Code Successfully Verified!             ║
║           φ² + 1/φ² = 3 = TRINITY                         ║
╚═══════════════════════════════════════════════════════════╝

---

What's Next?

Tutorial	Description
FPGA Blink	First FPGA synthesis and deployment
Sacred Math	Understanding φ, Trinity Identity

---

Troubleshooting

Problem	Solution
gen: command not found	Build TRI first: zig build tri
todo_manager.zig not found	Check output in trinity/output/
Test fails	Check generated code matches expected behavior

---

φ² + 1/φ² = 3 = TRINITY