overengineeringstudio / overengineeringstudio/effect-utils

Improve CLI output rendering (diagnostic-style errors, interactive TUI)

Open

#57 opened on Jan 11, 2026 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area:tui type:feature

Dominant language: TypeScript
Stars: 82
Forks: 2
Avg merge: 1d 8h
Merged PRs (30d): 121

Description

Context

Research into how oxlint renders its beautiful error/lint output. Goal: improve output of mono lint, mono check, etc.

Research Findings

oxlint uses miette - a Rust crate for fancy diagnostic reporting via GraphicalReportHandler.

Rust Libraries (reference)

Library	Stars	Notes
miette	2.5k	Used by 10.7k projects, Apache 2.0
ariadne	1.7k	Multi-line labels, color generator, MIT
codespan-reporting	600+	Simple API, used by many compilers
annotate-snippets	200+	Official rustc-style, Rust org maintained

JS/TS Options

Library	Status	Notes
ariadne-ts	✅ Active (v0.3.1, Jul 2025)	Port of Rust's ariadne, 34 stars, MIT
miette (npm)	⚠️ Stale (v0.1.0, May 2022)	JS port, only 21 stars, pre-1.0 API
@effect/printer-ansi	✅ Active	General doc formatter, not diagnostic-specific
opentui	✅ Active	Effect-native TUI framework for interactive use cases

Recommendation

ariadne-ts for diagnostic-style output (spans, labels, code snippets, colors)
opentui for interactive CLI experiences (menus, prompts, live updates)
Consider building Effect wrapper around ariadne-ts for better integration

Example (ariadne-ts)

import { Report, ReportKind, Label, Source } from 'ariadne-ts'

Report.build(ReportKind.Error, "file.ts", 42)
  .with_code("no-unused-vars")
  .with_message("Variable 'foo' is declared but never used")
  .with_label(Label.from([start, end]).with_message("unused variable"))
  .with_note("Consider removing or using this variable")
  .finish()
  .print(sources)

Use Cases

mono lint - show lint errors with code context
mono check - show type errors with spans
mono test - show test failures with diffs
Interactive prompts for commands that need user input

🤖 Generated with Claude Code

Contributor guide

No contributing guide indexed for this repository

First steps

Read the whole issue, then the project's contributing guide.
Comment on the issue to say you are picking it up — it saves two people doing the same work.
Fork the repository and make your change on a branch.
Open a pull request that references the issue number.

Research direction

Start by locating the CLI entry points for mono lint, mono check, and mono test, then trace how their current output is rendered. Review the proposed ariadne-ts and opentui approaches against the listed use cases. Done means a decided rendering direction and an implementation scope covering diagnostic context, type-error spans, test diffs, and interactive prompts.

Written by the indexing model from the issue text.

Assessment

Tech stack: typescript
Domain: cli, developer-experience
Issue type: Feature
Difficulty: 5/5
Estimated time: Over a week
Activity status: Stale
Clarity: Needs clarification
Newbie friendliness: 25/100