GO — Healthy across all four use cases

• Last commit 1d ago
• 10 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 90% of recent commits
• ⚠ Scorecard: default branch unprotected (0/10)

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against OpenSSF Scorecard}

YouPlot is a Ruby command-line tool that renders data visualizations directly in the terminal using Unicode characters. It wraps the UnicodePlot.rb library to generate bar charts, histograms, line plots, scatter plots, density plots, and box plots from CSV/TSV data piped via stdin or loaded from files, with customizable dimensions, titles, and axis limits. Single-package structure: exe/ contains the CLI entry points (uplot and youplot aliases), lib/youplot/ contains the core logic split into command parsing (command.rb), data ingestion (dsv.rb, parser.rb), backend rendering (backends/unicode_plot.rb), and configuration (options.rb, parameters.rb, aggregation.rb). Test fixtures in test/fixtures/ validate output against 40+ expected terminal renders.

Data analysts and DevOps engineers working in terminal environments who need quick exploratory data visualization without graphical display dependencies; users of Unix pipelines who want to inspect datasets inline during data processing workflows.

Actively maintained with CI/CD pipelines (GitHub Actions), type signatures via Steep (sig/ directory), comprehensive test fixtures covering all plot types, and available on multiple package managers (Homebrew, Rubygems, conda, Nix, Guix). Production-ready with clear semantic versioning.

Single-language dependency on UnicodePlot.rb gem and minimal visible dependency footprint (only Gemfile shown) reduces risk. However, terminal rendering behavior is platform-dependent (Windows vs Unix unicode support), and the project appears to have a small maintainer pool based on the red-data-tools GitHub org structure. No obvious breaking changes visible, but terminal compatibility edge cases may surprise users.

Dependabot is configured for dependency updates (.github/dependabot.yml). Documentation builds are automated (doc.yml workflow). Type safety is actively enforced via Steep (Steepfile present with sig/ type definitions). No specific breaking changes visible, suggesting stable maintenance mode rather than rapid feature development.

git clone https://github.com/red-data-tools/YouPlot.git
cd YouPlot
bundle install
bundle exec exe/uplot bar test/fixtures/iris.csv

Daily commands:

bundle install
bundle exec exe/uplot bar <input.csv>                    # barplot
bundle exec exe/uplot hist <input.csv>                   # histogram
bundle exec exe/uplot line -w 80 -h 20 <input.csv>      # lineplot with dimensions

• exe/youplot — Main entry point executable; all CLI invocations route through here, so understanding argument parsing and dispatch is essential.
• lib/youplot.rb — Root module that loads all core components; defines the public API surface and version.
• lib/youplot/command.rb — Core command dispatcher and orchestrator; translates CLI options into plotting operations, the heart of the application logic.
• lib/youplot/backends/unicode_plot.rb — Only rendering backend; all plot output ultimately flows through UnicodePlot, the critical graphics abstraction.
• lib/youplot/parser.rb — Input data parsing logic; handles CSV/TSV/raw stdin and converts unstructured data into structured rows/columns for plotting.
• lib/youplot/dsv.rb — Delimiter-separated value (DSV) reader; core data ingestion module for handling CSV/TSV files with charset detection.
• lib/youplot/options.rb — CLI option parsing and validation; defines all user-facing parameters and their constraints.

• Command Router (Ruby, lib/youplot/command.rb) — Maps CLI invocations to specific plot generation methods; orchestrates data flow
  • Failure mode: Crashes on invalid option combinations; user receives error message
• Data Parser (Ruby CSV, lib/youplot/dsv.rb, lib/youplot/parser.rb) — Reads stdin/files and detects format (CSV/TSV/raw lines); converts bytes to structured records
  • Failure mode: Encoding errors or malformed input silently skipped or raise exception; partial data plotted
• Aggregation Engine (Ruby Array/Hash, lib/youplot/aggregation.rb) — Transforms raw data into statistical summaries (histograms, counts, density bins)
  • Failure mode: Non-numeric data coerced to 0 or skipped; bin boundaries may be suboptimal for sparse data
• UnicodePlot Backend (UnicodePlot gem, lib/youplot/backends/unicode_plot.rb) — Renders data via UnicodePlot gem; handles all layout, scaling, and Unicode character selection
  • Failure mode: Terminal width/height limits may truncate plot; complex plots may overflow terminal

• User input (CLI args + stdin) → lib/youplot/options.rb — Arguments parsed into options hash
• lib/youplot/options.rb → lib/youplot/command.rb — Options routed to appropriate plot method
• stdin/file → lib/youplot/parser.rb — Raw bytes read and format detected
• lib/youplot/parser.rb → lib/youplot/dsv.rb — DSV detected; charset and delimiter inferred
• lib/youplot/dsv.rb → lib/youplot/command.rb — Rows and columns returned as structured arrays/hashes
• lib/youplot/command.rb → lib/youplot/aggregation.rb — Data aggregated (binned, counted) if needed for plot type
• Aggregated/raw data → lib/youplot/backends/unicode_plot.rb — Numeric series passed to UnicodePlot rendering
• `` → undefined — undefined

Add a new plot type

1. Add a new method in lib/youplot/command.rb following the pattern of existing plot methods (e.g., plot_barplot, plot_lineplot) (lib/youplot/command.rb)
2. Add corresponding CLI flag and option documentation in lib/youplot/options.rb (lib/youplot/options.rb)
3. Call the appropriate UnicodePlot method from lib/youplot/backends/unicode_plot.rb (e.g., UnicodePlot.barplot, UnicodePlot.lineplot) (lib/youplot/backends/unicode_plot.rb)
4. Add integration test in test/youplot/simple_test.rb with expected output snapshot fixture (test/youplot/simple_test.rb)

Support a new input format

1. Add parsing logic in lib/youplot/parser.rb to detect and handle the new format (lib/youplot/parser.rb)
2. If delimiter-based, extend lib/youplot/dsv.rb to support the delimiter and charset (lib/youplot/dsv.rb)
3. Add test cases in test/youplot/parser_test.rb with sample fixtures in test/fixtures/ (test/youplot/parser_test.rb)

Add a new plot customization option

1. Add the option definition and argument parser in lib/youplot/options.rb (lib/youplot/options.rb)
2. Pass the option value through lib/youplot/parameters.rb to carry metadata through the pipeline (lib/youplot/parameters.rb)
3. Use the parameter when calling UnicodePlot methods in lib/youplot/backends/unicode_plot.rb (lib/youplot/backends/unicode_plot.rb)
4. Add test in test/youplot/simple_test.rb and snapshot fixture for the new visualization (test/youplot/simple_test.rb)

• Ruby — Excellent for CLI tools; simple data manipulation; rapid development with rich string/array libraries
• UnicodePlot (Ruby gem) — Handles all low-level terminal graphics rendering; abstracts complex Unicode math and layout
• DSV (CSV/TSV) parsing — Standard interchange format for tabular data; majority of users pipe structured data from tools like awk, cut, jq

• Single UnicodePlot backend instead of multiple rendering engines

  • Why: Simpler codebase maintenance; UnicodePlot is mature and covers all plot types needed
  • Consequence: Cannot easily swap backends; terminal-only output (no GUI, no file export)

• Streaming stdin parsing instead of full in-memory load

  • Why: Enables processing of large datasets without memory explosion
  • Consequence: Some aggregations (histogram, density) must accumulate full dataset anyway; progressive mode limited

• Stateless command execution per invocation

  • Why: Simple UNIX philosophy; no state management needed; easy to parallelize/batch
  • Consequence: No session/configuration persistence; every plot is independent

• Interactive plot editing or mouse support in terminal
• Export to file formats (PNG, PDF, SVG)
• Graphical user interface
• Real-time streaming data updates
• Network data sources
• Statistical inference or hypothesis testing

Terminal width/height detection uses ENV variables or defaults; piping in narrow terminals may truncate plots unexpectedly. UTF-16 CSV support (test fixture iris_utf16.csv exists) but unclear if it's fully implemented—check lib/youplot/dsv.rb encoding handling. Unicode line-drawing characters may render as mojibake on Windows console without proper CHCP setup. No visible handling of NaN/Inf in numeric columns—may cause silent failures in aggregation. Delimiter auto-detection in DSV parser could misfire on ambiguous files.

• DSV (Delimiter-Separated Values) Parsing — YouPlot's core strength is auto-detecting CSV vs TSV vs arbitrary-delimiter formats; understanding dsv.rb's delimiter heuristics is essential for debugging data ingestion
• Unicode Box-Drawing Characters — Terminal plots are rendered using Unicode U+2500–U+257F block elements; understanding character width (1 vs 2 columns) is critical for alignment and Windows compatibility bugs
• Statistical Binning & Aggregation — Histograms and density plots require binning continuous data; lib/youplot/aggregation.rb implements Freedman-Diaconis or custom bin logic that differs from UnicodePlot defaults
• ANSI Terminal Escape Codes — UnicodePlot outputs ANSI color/formatting codes; understanding how terminal emulators interpret these is essential for color option debugging and platform compatibility
• RBS (Ruby Signature) Type Checking — sig/ directory uses RBS format validated by Steep; this is Ruby's static type system for a dynamically-typed language, essential for understanding type constraints in contribute changes
• OptionParser Pattern — lib/youplot/options.rb and command.rb use Ruby's built-in OptionParser for CLI argument routing; understanding how flags map to plot parameters is essential for adding new options
• Fixture-Based Regression Testing — test/fixtures/ contains 40+ .txt files with expected terminal output; any rendering change must match fixtures, making this a snapshot-test pattern for terminal output

• red-data-tools/unicode_plot.rb — The rendering backend that YouPlot wraps; essential dependency for all terminal plot generation
• red-data-tools/YouPlot2 — Experimental sibling project mentioned in README targeting pre-built binaries; divergent evolution path for distribution
• gnuplot/gnuplot — Traditional alternative for terminal plotting; YouPlot aims to replace this workflow without external dependencies
• asciicharts/asciicharts — JavaScript alternative for terminal charts; useful for learning cross-language terminal rendering patterns
• red-data-tools/red-data-tools — Parent organization providing data processing ecosystem; YouPlot fits into broader Ruby data tool suite

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for lib/youplot/backends/unicode_plot.rb

The backends directory only has unicode_plot.rb but there are no corresponding tests in test/youplot/ for the backend implementation. Given that this is the core rendering engine (as mentioned in README: 'Powered by UnicodePlot'), this module deserves dedicated unit tests covering plot type rendering, option handling, and edge cases.

• [ ] Create test/youplot/backends/ directory structure
• [ ] Add test/youplot/backends/unicode_plot_test.rb with tests for each plot type (bar, scatter, lineplot, histogram, boxplot, density, count)
• [ ] Test option parsing and parameter handling specific to unicode_plot backend
• [ ] Test edge cases like empty data, single values, and special characters
• [ ] Ensure test coverage for all public methods in lib/youplot/backends/unicode_plot.rb

Add integration tests for lib/youplot/command.rb CLI argument parsing

The command.rb file handles the main CLI interface, but test/youplot/ lacks dedicated tests for the command module. With exe/youplot and exe/uplot as entry points, the command parsing logic is critical. Current tests focus on specific data processing but not CLI workflow.

• [ ] Create test/youplot/command_test.rb to test CLI argument parsing
• [ ] Add tests for all major command flags (--type, --xlabel, --ylabel, --xlim, --ylim, --width, --height, --border, --canvas, --symbol)
• [ ] Test error handling for invalid argument combinations
• [ ] Add tests for file input handling (CSV, TSV, UTF-16 encoded files as seen in fixtures)
• [ ] Test the help/version output functionality

Expand lib/youplot/parser.rb test coverage in test/youplot/parser_test.rb

The parser module handles critical data parsing logic (DSV formats, encoding detection), but examining the existing test files shows parser_test.rb likely has gaps. With multiple fixture files including UTF-16 encoded CSVs (iris_utf16.csv) and various TSV formats, the parser needs robust test coverage for edge cases and encoding scenarios.

• [ ] Review current test/youplot/parser_test.rb and identify missing test cases
• [ ] Add tests for UTF-16 encoded file parsing (iris_utf16.csv is in fixtures but coverage unclear)
• [ ] Add tests for malformed CSV/TSV inputs (missing values, inconsistent columns, quotes)
• [ ] Add tests for different delimiter detection (comma, tab, pipe)
• [ ] Add tests for large file streaming performance (progressive_test.rb suggests streaming support)
• [ ] Test numeric type detection and conversion edge cases (integer-like-float.tsv suggests tricky cases)

• Add support for stdin without -t (title) flag gracefully failing or auto-generating titles from column headers—currently fixtures suggest titles are required but no error handling visible in command.rb for this case
• Extend lib/youplot/aggregation.rb with tests and documentation: sig/youplot/aggregation.rbs exists but test/aggregation_test.rb is not in the file list, suggesting coverage gap
• Add command alias validation: exe/youplot and exe/uplot both exist but README doesn't clarify which is preferred or if both are equally maintained—document or consolidate

YouPlot is a CLI plotting tool with a generally sound architecture. The primary security concerns are: (1) lack of visible input validation and sanitization in user-facing parser/command modules, (2) missing dependency vulnerability information, and (3) potential path traversal risks if file paths are user-controlled. The project appears well-maintained with CI/CD pipelines and uses established libraries (UnicodePlot). No hardcoded credentials were found. Recommendations focus on implementing robust input validation, regular dependency auditing, and path traversal protections.

• Medium · Potential Command Injection via User Input — lib/youplot/parser.rb, lib/youplot/command.rb, lib/youplot/dsv.rb. The codebase appears to be a CLI tool that processes user input (CSV/TSV files, command-line arguments) and passes it to plotting backends. The parser.rb and command.rb files likely process user-supplied data. Without visible input sanitization, there could be risks of command injection if user input is used in system calls or shell commands. Fix: Implement strict input validation and sanitization for all user inputs. Avoid using shell execution with unsanitized user data. Use Ruby's subprocess libraries (Process, Open3) with array-form arguments instead of string interpolation.
• Medium · Missing Dependency Vulnerability Information — Gemfile, youplot.gemspec. The dependency file content was not provided for analysis. The Gemfile exists but was not included in the analysis context. Without visibility into the gem dependencies and their versions, it's impossible to assess for known vulnerabilities in third-party libraries used by YouPlot. Fix: Run 'bundle audit' regularly to check for known vulnerabilities in dependencies. Pin dependency versions and keep them updated. Review Gemfile.lock for security advisories and apply patches promptly.
• Low · Potential Path Traversal in File Processing — lib/youplot/dsv.rb. The DSV parser (dsv.rb) processes file input without visible path validation checks. If the tool accepts file paths from user input, there could be a risk of path traversal attacks allowing access to files outside intended directories. Fix: Validate and sanitize all file path inputs. Use File.expand_path and verify that resolved paths are within expected directories. Implement whitelist-based path restrictions if possible.
• Low · No Visible Output Encoding Protection — lib/youplot/backends/unicode_plot.rb. The tool outputs data to terminal/stdout. While the risk is lower in a CLI context, there's no visible protection against potential issues with special characters or encoding attacks in the output rendering pipeline, particularly when handling untrusted data sources. Fix: Ensure proper UTF-8 encoding handling throughout. Validate and escape any user-controlled data before rendering. Use the unicode_plot library's built-in safety features for handling special characters.
• Low · Missing Security Headers in Documentation — README.md. Installation instructions recommend multiple package managers and direct gem installation. There's no visible guidance on verifying package integrity or using secure installation methods. Fix: Add security guidance to README including: verification of gem signatures, use of bundler security features, instructions for auditing dependencies, and recommendations to use trusted package sources.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/red-data-tools/YouPlot shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live red-data-tools/YouPlot repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/red-data-tools/YouPlot.

What it runs against: a local clone of red-data-tools/YouPlot — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in red-data-tools/YouPlot | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of red-data-tools/YouPlot. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/red-data-tools/YouPlot.git
#   cd YouPlot
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of red-data-tools/YouPlot and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "red-data-tools/YouPlot(\\.git)?\\b" \\
  && ok "origin remote is red-data-tools/YouPlot" \\
  || miss "origin remote is not red-data-tools/YouPlot (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "exe/youplot" \\
  && ok "exe/youplot" \\
  || miss "missing critical file: exe/youplot"
test -f "lib/youplot.rb" \\
  && ok "lib/youplot.rb" \\
  || miss "missing critical file: lib/youplot.rb"
test -f "lib/youplot/command.rb" \\
  && ok "lib/youplot/command.rb" \\
  || miss "missing critical file: lib/youplot/command.rb"
test -f "lib/youplot/backends/unicode_plot.rb" \\
  && ok "lib/youplot/backends/unicode_plot.rb" \\
  || miss "missing critical file: lib/youplot/backends/unicode_plot.rb"
test -f "lib/youplot/parser.rb" \\
  && ok "lib/youplot/parser.rb" \\
  || miss "missing critical file: lib/youplot/parser.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/red-data-tools/YouPlot"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.