Shopify / Shopify/roast

Format exceptions messages/traces to point to the problem in the workflow, not in Roast internals

Open
#457 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Ruby
Stars
1.2k
Forks
76
PR merge metrics
No merged PRs in 30d

Description

Format exception messages to point to workflow problems rather than showing Roast internals. DSL cog errors should display user-friendly messages that help identify workflow issues rather than exposing internal Ruby stack traces.

Problem

When errors occur, Ruby's stack trace shows Roast internals:

lib/roast/dsl/execution_manager.rb:142:in `block in run!'
lib/roast/dsl/cog.rb:89:in `instance_exec'

Users need to see DSL execution context:

In workflow: examples/my_workflow.rb
  In execute block (line 15)
    In cog cmd!(:deploy) at line 18
      In input block (line 18)
        Error: command not found: deploy-script

Solution: Shadow Execution Stack

Maintain a thread-local execution context stack that tracks DSL-level information (workflow → scope → cog → block) separate from Ruby's call stack. This is the standard approach for DSL interpreters (similar to JavaScript source maps, template engine traces).

See EXECUTION_CONTEXT_TRACKING_PLAN.md for full architecture.

Success Criteria

  • Implement ExecutionContextTracker for thread-local context stack management
  • Implement ExecutionFrame to capture DSL context (workflow, scope, cog, line numbers)
  • Instrument Workflow.prepare! to push/pop workflow frames
  • Instrument ExecutionManager.prepare!/run! to track scope entry/exit
  • Instrument Cog.run! to track cog execution and input blocks
  • Instrument on_execute to track cog instantiation
  • Implement thread safety for async tasks (context inheritance)
  • Implement DslErrorFormatter to render DSL traces
  • Integrate with exception handling at ExecutionManager and CLI levels
  • Create test workflows with intentional errors for verification
  • Add RBI-style typing

Contributor guide

Open the contributing guide

First steps

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

Research direction

Start with EXECUTION_CONTEXT_TRACKING_PLAN.md, then inspect lib/roast/dsl/execution_manager.rb and lib/roast/dsl/cog.rb, including Workflow.prepare!, ExecutionManager.prepare!/run!, Cog.run!, and on_execute. Trace how exceptions reach the execution manager and CLI. Done means DSL context is tracked and formatted for workflow errors, with the listed success criteria covered.

Written by the indexing model from the issue text.

Assessment

Tech stack
ruby
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.