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.

GO — Healthy across all four use cases

• Last commit 3d ago
• 8 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Single-maintainer risk — top contributor 92% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

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 | Last commit ≤ 33 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"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
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).

YouPlot is a Ruby command-line tool that renders plots directly in the terminal using Unicode characters, powered by the UnicodePlot library. It converts tabular data (CSV, TSV) piped via stdin into terminal-drawable visualizations including bar charts, histograms, line plots, scatter plots, density plots, and box plots. Monolithic structure: exe/uplot and exe/youplot are entry points wrapping lib/youplot.rb; lib/youplot/ contains domain logic split into lib/youplot/command.rb (CLI orchestration), lib/youplot/parser.rb (input parsing), lib/youplot/dsv.rb (CSV/TSV handling), lib/youplot/options.rb (flag parsing), lib/youplot/parameters.rb (plot configuration), and lib/youplot/backends/ (unicode_plot.rb and processing.rb for rendering engines).

Data engineers and command-line users who need quick data visualization without leaving the terminal; developers analyzing datasets via shell pipelines and wanting immediate graphical feedback without GUI dependencies or external tools.

Production-ready and actively maintained. The project has CI/CD via GitHub Actions (test, doc workflows in .github/workflows/), comprehensive test fixtures covering all plot types (60+ fixture files in test/fixtures/), is distributed via multiple package managers (Homebrew, gem, Nix, Guix, conda), and has stable documentation on RubyDoc. Regular dependency updates via Dependabot indicate ongoing maintenance.

Low risk for a stable tool. Single-language Ruby implementation minimizes dependency complexity; the only critical dependency is UnicodePlot (inspectable in Gemfile). No evidence of abandoned state—CI is green and fixture tests are current. Risk is primarily single-maintainer (red-data-tools org), but the tool solves a narrow, well-defined problem with no breaking-change surface area.

Repository appears to be in stable maintenance—no specific milestones or active PRs visible in the provided data, but Dependabot updates (in .github/dependabot.yml) show automated dependency management is active. The codebase is complete with all major plot types implemented and tested.

git clone https://github.com/red-data-tools/YouPlot.git
cd YouPlot
bundle install
bundle exec exe/uplot --help

Or install via gem: gem install youplot && uplot --help

Daily commands:

bundle exec exe/uplot bar -d, < data.csv
bundle exec exe/uplot line -d, -w 50 -h 15 < data.csv
bundle exec exe/uplot hist --nbins 20 < data.txt

All commands read from stdin; no server or daemon mode.

• lib/youplot/command.rb: Core orchestrator: routes CLI commands (bar, line, hist, etc.) to appropriate rendering logic; main entry point for request flow
• lib/youplot/backends/unicode_plot.rb: Primary rendering engine; wraps UnicodePlot.rb calls and translates parsed data into terminal-drawable plots
• lib/youplot/dsv.rb: Handles CSV/TSV parsing from stdin; critical for data ingestion from piped input
• lib/youplot/options.rb: CLI argument parser; defines all user-facing flags (width, height, title, xlim, ylim, delimiter, etc.)
• lib/youplot/parser.rb: Transforms raw delimited input into structured data suitable for plotting (columns, rows, types)
• exe/uplot: Entry point executable; loads youplot gem and delegates to lib/youplot.rb

Adding a new plot type: Add handler in lib/youplot/command.rb and corresponding method in lib/youplot/backends/unicode_plot.rb. Fixing parsing bugs: Edit lib/youplot/dsv.rb (CSV/TSV handling) or lib/youplot/parser.rb (input format). New CLI flags: Modify lib/youplot/options.rb. Adding tests: Create fixtures in test/fixtures/ matching pattern <description>-<plottype>.txt, then assert output matches.

No hidden critical traps identified from file structure. The tool reads only from stdin—no file handles, database connections, or network I/O. Character encoding edge case: test/fixtures/iris_utf16.csv suggests UTF-16 support may require explicit handling in dsv.rb. Delimiter auto-detection is not obvious from file names—defaults to tab in lib/youplot/dsv.rb, require -d flag for CSV (comma). Terminal width/height detection on resize not apparent in parameters.rb—may require TTY feature negotiation.

• Delimiter-Separated Values (DSV) Parsing — YouPlot's core strength is converting arbitrary delimited formats (CSV, TSV, pipe-separated) into plots; understanding DSV parsing edge cases (quoted fields, escaped delimiters, multi-line cells) is essential for extending lib/youplot/dsv.rb
• Unicode Box Drawing Characters — Terminal plots are rendered entirely using Unicode box-drawing blocks (U+2500–U+257F range); understanding these characters' width (often 0.5 or 1 em), combining effects, and terminal fallback behavior is critical for plot alignment and rendering in lib/youplot/backends/unicode_plot.rb
• Command Pattern — lib/youplot/command.rb routes CLI commands (bar, line, hist, scatter, etc.) as discrete command objects; understanding this pattern helps extend plot types and map new verbs to rendering strategies
• Strategy Pattern (Backends) — lib/youplot/backends/ abstracts rendering implementations (unicode_plot.rb vs. processing.rb); allows swapping rendering engines without changing command logic, useful for adding new output formats (SVG, ANSI color, etc.)
• TTY/Terminal Capability Negotiation — YouPlot writes to terminal; automatic width/height detection (parameters.rb), ANSI color support detection, and fallback to ASCII-only mode depend on terminal capabilities; knowing when stdin is a pipe vs. interactive terminal affects plot rendering
• Streaming/Pipeline Data Processing — YouPlot reads from stdin as a data pipeline; understanding how Ruby processes unbounded input streams (lib/youplot/parser.rb must buffer or stream wisely) is crucial for memory efficiency with large datasets

• red-data-tools/unicode_plot.rb — Direct dependency and rendering engine; all terminal plot generation delegates here
• bkrem/grepplot — Alternative terminal plotting tool for grep output; solves similar problem (CLI visualization) with different input model
• mkaz/termgraph — Python-based terminal plotter; comparable feature set (bar, line, histogram) and use case (piped stdin visualization)
• red-data-tools/red-arrow — Red Data Tools' Arrow implementation; complements YouPlot for efficient columnar data handling in data pipelines
• sgreben/jp — JSON-to-plot CLI tool; orthogonal input format but same terminal rendering philosophy

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/command.rb

The command.rb file is a core module that handles CLI argument parsing and execution, but there are no dedicated unit tests in test/youplot/ for it. This is a critical integration point that deserves specific test cases for different plot types, edge cases in parameter validation, and error handling paths. Currently only parser_test.rb and simple_test.rb exist, but command.rb logic itself lacks direct coverage.

• [ ] Create test/youplot/command_test.rb with test cases for each plot type (bar, scatter, line, histogram, box, count, density)
• [ ] Add tests for invalid flag combinations and error messages
• [ ] Add tests for data source handling (stdin, files, different encodings like iris_utf16.csv)
• [ ] Test options parsing edge cases (margin, padding, width, height, xlim, ylim combinations)

Add CI workflow for testing multiple Ruby versions and platforms

The existing .github/workflows/ci.yml likely tests on a single Ruby version. YouPlot should ensure compatibility across multiple Ruby versions (2.7+, 3.0, 3.1, 3.2, 3.3) since it's distributed via RubyGems and Homebrew. This is especially important given the UTF-16 encoding test fixture and platform-specific terminal rendering concerns.

• [ ] Update .github/workflows/ci.yml to use matrix strategy with Ruby versions: 2.7, 3.0, 3.1, 3.2, 3.3
• [ ] Add matrix for OS (ubuntu-latest, macos-latest) since Homebrew distribution requires macOS compatibility
• [ ] Test installation and basic functionality (e.g., 'youplot --version', pipe data through uplot) on each platform
• [ ] Consider adding a workflow for testing the gem can be successfully built and published

Add integration tests for data format handling in lib/youplot/dsv.rb

The dsv.rb file handles CSV/TSV parsing with test/youplot/dsv_test.rb, but there are no specific tests validating that the fixture files (iris.csv, iris_utf16.csv, simple.tsv, IRIStsv.tsv) are correctly parsed and produce expected plot outputs. This gap means regressions in parsing could go undetected. Add tests that verify end-to-end: fixture file → parsing → plot generation.

• [ ] Create test/youplot/dsv_integration_test.rb (or expand dsv_test.rb) with tests for each fixture file
• [ ] Add tests for iris.csv (standard CSV), iris_utf16.csv (encoding handling), IRIStsv.tsv (TSV variant), and simple.tsv
• [ ] Verify that parsed data produces consistent plot outputs matching the reference fixtures in test/fixtures/ (e.g., iris-scatter.txt, simple-lineplot.txt)
• [ ] Add error handling tests for malformed CSV/TSV and edge cases (empty files, missing columns, inconsistent row lengths)

• Add test coverage for lib/youplot/parameters.rb—no fixture files reference parameter validation, suggesting untested edge cases like invalid range specs (e.g., --xlim abc,def or missing comma). Create test cases in test/ for malformed plot parameters.
• Extend lib/youplot/dsv.rb to auto-detect delimiter (comma vs. tab vs. pipe) instead of requiring -d flag—implement heuristic (sample first 5 lines, count delimiters) and add fixtures in test/fixtures/ for auto-detect validation (e.g., simple-lineplot-auto-delim.txt).
• Add color support to lib/youplot/backends/unicode_plot.rb—UnicodePlot likely supports colors; wrap calls with color output flags and create colored fixture examples in test/fixtures/ (e.g., iris-barplot-colors.txt), then update lib/youplot/options.rb to expose --color flag.

YouPlot is a relatively simple command-line plotting tool with moderate security posture. The primary concerns are: (1) potential command/shell injection vulnerabilities in data processing and backend invocation pipelines, (2) unsafe file handling with user-supplied CSV/TSV inputs including encoding handling, and (3) lack of visible input validation for plotting parameters. The codebase contains test fixtures and CI/CD configuration suggesting active maintenance. No hardcoded secrets were identified in the provided file structure. The Ruby/Gem-based architecture is generally safer than languages like C/C++, but command execution and file processing remain risk areas. Recommendations focus on rigorous input validation, sanitization of all user-supplied data, and security scanning in the dependency chain.

• Medium · Potential Command Injection in DSV/Parser Processing — lib/youplot/dsv.rb, lib/youplot/parser.rb, lib/youplot/command.rb, lib/youplot/backends/processing.rb. The application processes CSV/TSV files and command-line arguments. Given the file structure includes 'lib/youplot/dsv.rb', 'lib/youplot/parser.rb', and 'lib/youplot/command.rb', there is a risk of command injection if user input is passed unsanitized to system commands or shell operations. The tool draws plots based on user-provided data which could be exploited if the underlying data processing or backend invocation doesn't properly sanitize inputs. Fix: Ensure all user inputs and file data are properly validated and sanitized before being used in any system calls or backend operations. Use parameterized/escaped execution rather than string interpolation for any shell commands. Review all calls to system(), exec(), backticks, or Open3 methods.
• Medium · Unsafe File Handling with User-Supplied Data — lib/youplot/dsv.rb, test/fixtures/iris_utf16.csv. The application accepts CSV/TSV files as input from users and processes them. There's potential for path traversal attacks if file paths are not properly validated. Additionally, UTF-16 encoded files are supported (iris_utf16.csv in test fixtures), which could introduce encoding-based vulnerabilities if not properly validated. Fix: Implement strict file path validation to prevent directory traversal attacks. Validate and sanitize all file inputs. Use Ruby's File.expand_path and ensure paths remain within expected directories. Be cautious with encoding conversions and validate file encodings before processing.
• Low · Dependency Management Lacking Explicit Pinning — Gemfile, youplot.gemspec. The Gemfile and gemspec files are present but not provided for review. Without seeing the dependency versions, it's unclear if dependencies are pinned to specific versions or if floating version constraints are used. This could lead to supply chain risks if transitive dependencies have vulnerabilities. Fix: Review and implement semantic versioning with upper bounds on all dependencies. Use bundler-audit or similar tools to regularly scan for vulnerable dependencies. Consider using Gemfile.lock with bundler to ensure reproducible builds. Run dependency security checks in CI/CD pipeline.
• Low · Insufficient Input Validation on Plot Parameters — lib/youplot/options.rb, lib/youplot/parameters.rb, lib/youplot/command.rb. The application accepts various plotting parameters (width, height, margins, padding, limits) through command-line arguments as seen in test fixtures. Without visible validation logic, malformed or malicious values could cause denial of service (excessive memory/CPU usage) or unexpected behavior. Fix: Implement strict validation for all numeric parameters with reasonable bounds. Define minimum and maximum limits for width, height, margins, padding, and axis limits. Validate all string parameters for length and content. Add error handling with user-friendly error messages.

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

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

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