Caching & Performance

# Cache control options
--cache <config>                   # Cache configuration string
--force                           # Ignore existing cache, force execution
--no-cache                        # Disable all caching
--remote-only                     # Use only remote cache
--remote-cache-read-only          # Read-only remote cache access

# Cache behavior examples
turbo run build --cache=local:rw,remote:r
turbo run build --force
turbo run build --no-cache
turbo run build --remote-only

# Cache configuration format: <location>:<permissions>
local:rw        # Local cache: read and write
local:r         # Local cache: read only
local:w         # Local cache: write only
remote:rw       # Remote cache: read and write  
remote:r        # Remote cache: read only
remote:w        # Remote cache: write only

# Combined configurations (comma-separated)
local:rw,remote:r      # Local read/write, remote read-only
local:r,remote:rw      # Local read-only, remote read/write

# Use only local cache
turbo run build --cache=local:rw

# Use remote cache for reading, local for writing
turbo run build --cache=local:rw,remote:r

# Force execution and update both caches
turbo run build --cache=local:w,remote:w --force

# Read from remote, write to local only
turbo run build --cache=local:w,remote:r

# Cache directory options
--cache-dir <path>                 # Override cache directory location
--cache-workers <number>           # Concurrent cache operations (default: 10)

# Cache directory examples
turbo run build --cache-dir=./custom-cache
turbo run build --cache-workers=20

# Use custom cache directory
turbo run build --cache-dir=/tmp/turbo-cache

# Increase cache operation concurrency
turbo run build --cache-workers=20

# Combine with remote cache settings
turbo run build --cache-dir=./build-cache --remote-only

# Performance profiling options
--profile <file>                   # Save performance profile with identifiable data
--anon-profile <file>              # Save anonymous performance profile
--trace <file>                     # Save performance trace (global option)

# Profiling examples
turbo run build --profile=build-profile.json
turbo run build --anon-profile=anon-build-profile.json
turbo run build --trace=build-trace.json

# Generate detailed profile for performance analysis
turbo run build --profile=profiles/build-$(date +%Y%m%d).json

# Generate anonymous profile for sharing
turbo run build --anon-profile=anon-profile.json

# Capture trace data for Chrome DevTools
turbo run build --trace=chrome-trace.json

# Profile specific filtered packages
turbo run build --filter="@myorg/slow-package" --profile=slow-package.json

--graph <file>                     # Generate task execution graph
--graph                           # Output graph to stdout (DOT format)

# Supported graph formats
graph.svg          # SVG image
graph.png          # PNG image  
graph.jpg          # JPEG image
graph.pdf          # PDF document
graph.json         # JSON data
graph.html         # Interactive HTML
graph.mermaid      # Mermaid diagram
graph.dot          # DOT/Graphviz format

# Generate interactive HTML graph
turbo run build --graph=task-graph.html

# Generate SVG for documentation
turbo run build test lint --graph=full-pipeline.svg

# Output DOT format to stdout for further processing
turbo run build --graph | dot -Tpng > custom-graph.png

# Generate JSON for programmatic analysis
turbo run build --filter="@myorg/*" --graph=org-tasks.json

--summarize                        # Generate execution summary
--summarize=true                   # Explicit enable
--summarize=false                  # Explicit disable

# Summary examples
turbo run build --summarize
turbo run build test --summarize --profile=detailed.json

# Generate summary for build analysis
turbo run build --summarize

# Combine summary with profiling
turbo run build test lint --summarize --profile=full-analysis.json

# Summary with custom cache settings
turbo run build --cache=local:w,remote:r --summarize

# Daemon control options
--daemon                           # Force daemon usage
--no-daemon                        # Force disable daemon
# Default: automatic detection based on environment

# Daemon examples
turbo run build --daemon
turbo run build --no-daemon

# Force daemon usage for maximum performance
turbo run build --daemon

# Disable daemon for CI environments
turbo run build --no-daemon

# Let Turbo decide automatically (default)
turbo run build

interface CacheConfig {
  local: "r" | "w" | "rw";
  remote: "r" | "w" | "rw";
}

interface ProfileData {
  tasks: TaskProfile[];
  summary: ExecutionSummary;
  timing: TimingData;
}

interface TaskProfile {
  task: string;
  package: string;
  duration: number;
  cache_hit: boolean;
  cache_source: "local" | "remote" | null;
  dependencies: string[];
}

interface ExecutionSummary {
  total_time: number;
  cache_hit_rate: number;
  tasks_executed: number;
  tasks_cached: number;
  parallel_efficiency: number;
}

interface TimingData {
  start_time: string;
  end_time: string;
  task_timings: Record<string, number>;
  cache_timings: Record<string, number>;
}

interface GraphData {
  nodes: GraphNode[];
  edges: GraphEdge[];
  metadata: GraphMetadata;
}

interface GraphNode {
  id: string;
  label: string;
  package: string;
  type: "task" | "package";
  duration?: number;
  cache_hit?: boolean;
}

interface GraphEdge {
  from: string;
  to: string;
  type: "depends" | "triggers";
}

interface GraphMetadata {
  generated_at: string;
  turbo_version: string;
  total_tasks: number;
  format: "svg" | "png" | "json" | "html" | "mermaid" | "dot";
}