🐃 YakShave

A Raku module for parsing, analyzing, and visualizing dependency chains in yak shaving narratives.

Parses yak shaving stories (sequences of task dependencies) using Raku grammars
Creates a visual dependency tree showing the path from your original goal to your current task
Calculates a "Yak Shaving Factor" to measure how deep you've gone into dependencies
Provides a step-by-step path back to your original goal

I wanted to deploy my app.
But first I needed to write a yak shaving analyzer.
Which required learning Raku grammars.
So now I'm reading about Unicode emoji codepoints.

🧶 The Art of Yak Shaving

In the wild landscapes of software development, a peculiar ritual exists known as "yak shaving." This ancient practice occurs when a seemingly simple task spirals into a chain of increasingly unrelated prerequisites.

YakShave is a Raku module that transforms these woolly narratives into structured dependency chains, helping you visualize just how far you've strayed from your original task and find your way back to productivity.

🪒 Shear Brilliance

I want to deploy my app.
But first I need to fix tests.
Which requires updating the framework.
So now I'm reading about Jest internals.

Becomes:

📌 deploy my app
  📌 fix tests
    📌 updating the framework
      🐃 reading about Jest internals

🐃 Installation: Preparing Your Shearing Tools

# I want to install YakShave
# But first I need to install Raku
# Which requires setting up a package manager
zef install YakShave

🪒 Usage: Your First Shave

The Simple Trim

use YakShave;

# Document your yak shaving journey
my $story = q:to/END/;
I want to ship the feature.
But first I need to write tests.
Which requires fixing the test framework.
So now I'm learning Jest internals.
END

# See how woolly your yak has become
say visualize-story($story);

The Full Grooming Experience

# Run the basic example
raku examples/basic-example.raku

# Try the interactive mode
raku examples/interactive.raku

# See a complex analysis
raku examples/epic-yakshave.raku

🧮 Examples Included

The module comes with several example scripts in the examples/ directory:

basic-example.raku: Shows basic dependency visualization and metrics
complex-chain.raku: Demonstrates a multi-level dependency chain with detailed analysis
epic-yakshave.raku: An epic yak shaving journey with comprehensive metrics and visualizations
file-input.raku: Process yak shaving stories from external files
interactive.raku: Build your dependency tree interactively
manual-yakstack.raku: Manually construct dependency graphs for more complex scenarios
grammar-demo.raku: Focused demonstration of grammar parsing capabilities
enhanced-grammar-demo.raku: Showcases the comprehensive grammar support for natural language variations

📘 API Documentation

Core Functions

# Parse a yak shaving story and return an actions object with the dependency tree
sub parse-story(Str $story, Bool :$debug = False) is export

# Parse a story and return a string visualization of the dependency tree
sub visualize-story(Str $story, Bool :$debug = False) is export

YakShave::YakStack Methods

# Add a dependency relationship: task1 depends on task2
method add-dependency(Str $task1, Str $task2)

# Get all direct dependencies of a task
method dependencies-of(Str $task)

# Get all tasks that directly depend on a given task
method dependents-of(Str $task)

# Get all tasks in the dependency graph
method all-tasks()

# Find the root task (the original goal with no dependents)
method root-task()

# Find the current task (the one with no dependencies)
method current-task()

# Get a string visualization of the dependency tree
method visualize()

Usage Examples

use YakShave;

# Simple visualization
my $story = 'I want to deploy my app.
But first I need to fix tests.';
say visualize-story($story);

# Manual construction
use YakShave::YakStack;
my $stack = YakShave::YakStack.new;
$stack.add-dependency("deploy my app", "fix tests");
$stack.add-dependency("fix tests", "update test framework");
say $stack.visualize;
say "Original goal: ", $stack.root-task;

🧠 The Yakified Mindset: Recognized Thought Patterns

The module recognizes a comprehensive set of yak shaving language patterns, including:

Original Goal Expressions

"I want to deploy my app"
"My goal is to fix the bug"
"I'm attempting to optimize the code"
"It all started when I tried to update the library"

Dependency Statements

"But first I need to fix tests"
"This requires updating the database"
"Before I can do that, I need to install the tools"
"I discovered that I need to update the compiler"
"But there's a blocking issue: I need to get permission"

Current Task Expressions

"So now I'm reading documentation"
"I'm currently studying the API"
"I've ended up researching Linux permissions"
"Somehow I'm now learning about Unicode"

Alternative & Parallel Paths

"Alternatively, I could use a different approach"
"Meanwhile, I also need to update the tests"

"Actually, I need to use a different library"
"To clarify, I'm trying to implement authentication"

The enhanced grammar understands a wide variety of natural language patterns, making it easier to document your yak shaving adventures exactly as you would describe them conversationally.

📊 Understanding Your Yak's Condition

The Dependency Tree 🌳

Trace the meandering path that led you from your goal to your current distraction:

📌 The tasks in your dependency chain
🐃 The current yak you're actually shaving

The Yak Factor 📏

Quantifying your distractibility:

0: Focused! Working directly on your goal
1: Minor detour, barely a yak
2: Classic yak shave, getting fuzzy
3-5: Deep in yak territory, fur flying everywhere
6+: Epic yak odyssey, you might need industrial shears

The Path Home 🧭

A step-by-step guide to navigate back through the thicket of dependencies to your original goal.

Shaving Progress 📈

See your yak's current grooming status:

🦲 Completely shaved yak - All dependencies documented, you've achieved peak yak shaving status
💇 Half-shaved yak - You've made good progress understanding your diversions
🧔 Partially shaved yak - The yak is taking shape, but still woolly in patches
🦙 Barely shaved yak - Just getting started on documenting your detours
🐃 Completely unshaved yak - Wild and woolly, you haven't started tracking dependencies or you don't have any. Congratulations!

🧳 Real-World Yakspeditions

I want to fix a minor CSS issue.
But first I need to update the styling framework.
Which requires upgrading the package manager.
Which requires updating Node.js.
Which requires fixing system permissions.
So now I'm learning about Unix user groups.

For a truly epic yakspedition, check out the epic-yakshave.raku example which includes:

I want to deploy the new microservice to production.
But first I need to set up the CI/CD pipeline.
Which requires configuring the Kubernetes cluster.
Which requires upgrading the cloud provider SDK.
Which requires fixing the authentication system.
Which requires updating our identity provider.
Which requires migrating to the new user database schema.
Which requires understanding the legacy data model.
Which requires talking to the original architect.
Which requires finding their contact information.
So now I'm searching through old company directories.

🧠 Yak Shaving Proverbs

"The journey of a thousand miles begins with shaving a single yak." - Ancient programmer proverb

"It's yaks all the way down." - Recursive wisdom

"Beware the yak you think needs shaving; sometimes the real yak is yourself." - Deep thoughts

"A shaved yak today keeps the project manager away." - Developer wisdom

"When you stare into the yak, the yak stares back at you." - Friedrich Codesche

📜 License

Artistic License 2.0 (because even licensing can be its own yak shave)