utf8proj

Explainable, deterministic project scheduling from plain text.
CLI + LSP + WebAssembly — schedules you can read, diff, and trust.

🚀 Try the Interactive Demo — no install, runs in your browser

▶️ 10-min Overview

▶️ Deep Dive: Architecture & Design

_{AI-generated with NotebookLM}

---

Why utf8proj?

• Explainable — Every scheduling decision has a traceable diagnostic code. No black boxes.
• Deterministic — Same input always produces the same output. Perfect for CI/CD and audits.
• Git-friendly — Plain text .proj files you can diff, review, and version control.

---

Installation

Download Binary (Recommended)

Linux:

curl -LO https://github.com/alanbld/utf8proj/releases/latest/download/utf8proj-v0.10.0-x86_64-unknown-linux-gnu.tar.gz
tar xzf utf8proj-v0.10.0-x86_64-unknown-linux-gnu.tar.gz
sudo mv utf8proj /usr/local/bin/

macOS (Apple Silicon):

curl -LO https://github.com/alanbld/utf8proj/releases/latest/download/utf8proj-v0.10.0-aarch64-apple-darwin.tar.gz
tar xzf utf8proj-v0.10.0-aarch64-apple-darwin.tar.gz
sudo mv utf8proj /usr/local/bin/

macOS (Intel):

curl -LO https://github.com/alanbld/utf8proj/releases/latest/download/utf8proj-v0.10.0-x86_64-apple-darwin.tar.gz
tar xzf utf8proj-v0.10.0-x86_64-apple-darwin.tar.gz
sudo mv utf8proj /usr/local/bin/

Windows (PowerShell):

Invoke-WebRequest -Uri "https://github.com/alanbld/utf8proj/releases/latest/download/utf8proj-v0.10.0-x86_64-pc-windows-msvc.zip" -OutFile utf8proj.zip
Expand-Archive utf8proj.zip -DestinationPath .

Build from Source (Rust users)

cargo install utf8proj-cli

Verify Installation

utf8proj --version
# utf8proj 0.10.0

---

Quick Start (60 seconds)

1. Create example.proj:

project "Sprint 1" { start: 2025-02-01 }

resource dev "Developer" { rate: 850/day }

task design "Design" { effort: 3d, assign: dev }
task build "Build" { effort: 5d, assign: dev, depends: design }
milestone done "Done" { depends: build }

2. Run:

utf8proj schedule example.proj

3. Or try instantly in the browser: alanbld.github.io/utf8proj

---

What You Get

Component	Purpose
utf8proj CLI	Schedule, validate, render Gantt charts
utf8proj-lsp	IDE support: hover, go-to-definition, diagnostics
WASM Playground	Browser-based scheduling with live preview
Renderers	HTML, SVG, Mermaid, PlantUML, Excel (XLSX)

Scheduling & Analysis

• CPM Scheduling — Critical path with FS/SS/FF/SF dependencies and lag
• Resource Leveling — Deterministic conflict resolution with audit trail
• Calendar-Aware — Working days, weekends, holidays with impact analysis
• Temporal Regimes — Work, Event, Deadline modes control date handling
• Progress Tracking — Status date, remaining duration, earned value (SPI)
• Focus View — Filter large Gantt charts by task prefix

40+ Diagnostic Codes

Every decision is explained:

• E*: Errors (circular deps, infeasible constraints)
• W*: Warnings (overallocation, wide cost ranges)
• L*: Leveling decisions (L001-L004)
• C*: Calendar impact (C001-C023)
• P*: Progress tracking (P005-P006)
• R*: Temporal regimes (R001-R005)

---

CLI Examples

# Validate (fast, CI-friendly)
utf8proj check project.proj --strict

# Schedule with leveling
utf8proj schedule -l project.proj

# Interactive HTML Gantt
utf8proj gantt project.proj -o timeline.html -f html

# Excel workbook with calendar analysis
utf8proj gantt project.proj -o report.xlsx -f xlsx --include-calendar

# Focus on specific tasks
utf8proj gantt project.proj -o backend.html -f html --focus="backend"

---

Library Usage

use utf8proj_core::{Project, Task, Resource, Duration, Scheduler};
use utf8proj_solver::CpmSolver;

let mut project = Project::new("My Project");
project.start = chrono::NaiveDate::from_ymd_opt(2025, 2, 1).unwrap();
project.tasks = vec![
    Task::new("design").effort(Duration::days(5)),
    Task::new("build").effort(Duration::days(10)).depends_on("design"),
];

let solver = CpmSolver::with_leveling();
let schedule = solver.schedule(&project)?;
println!("Critical path: {:?}", schedule.critical_path);

---

Documentation

Document	Purpose
Quick Reference	DSL syntax cheat sheet
Grammar Spec	Complete .proj syntax
Diagnostics	All diagnostic codes
Temporal Regimes	Work/Event/Deadline scheduling modes
Editor Setup	VS Code, Neovim, Vim, Zed
Explainability Manifesto	Design philosophy

---

Comparison

Feature	utf8proj	TaskJuggler	MS Project
File Format	Text (.proj)	Text (.tjp)	Binary (.mpp)
Version Control	Excellent	Good	Poor
Explainability	First-class	Limited	None
Resource Leveling	Deterministic	Optimizer	Black box
License	MIT/Apache-2.0	GPL-2.0	Commercial
Single Binary	Yes	No (Ruby)	No

---

Development

git clone https://github.com/alanbld/utf8proj
cd utf8proj
cargo build --workspace
cargo test --workspace

---

License

Licensed under MIT or Apache-2.0, at your option.

---

_{Built with Rust. Designed for transparency.}