Blitz.MixWorkspace (blitz v0.3.0)

Config-driven runner for Mix-oriented multi-project workspaces.

Workspace configuration lives in the root project's mix.exs under the :blitz_workspace key. Blitz.MixWorkspace expands the configured project patterns, builds isolated child mix commands, and runs staged workspace tasks through Blitz.

Parallelism stays workspace-owned:

base config describes task weight
multiplier describes machine size
:auto multiplier mode scales from local schedulers and memory
per-task overrides and CLI -j still take precedence when present

Summary

Types

runner_args()

stage()

task_name()

workspace_config()

Functions

autodetect_multiplier(opts \\ [])

Returns a recommended workspace multiplier for the current machine.

command_env(workspace_config, project_path, task)

Builds environment overrides for a project/task pair.

hashed_project_name(base_name, project_path, opts \\ [])

Builds a stable hashed name for a workspace project path.

load!(project_config \\ Mix.Project.config())

Loads and normalizes workspace configuration from the current Mix project.

max_concurrency(workspace_config, task, runner_override \\ nil)

Returns the effective concurrency for a workspace task.

package_paths()

Returns workspace project paths excluding the root "." entry.

package_paths(workspace_config)

Returns workspace project paths excluding the root "." entry.

plan(workspace_config, task, args \\ [])

Builds the staged execution plan for a workspace task.

project_paths()

Returns workspace project paths in stable configured order.

project_paths(workspace_config)

Returns workspace project paths in stable configured order.

resolve_task_name!(workspace_config, task_name)

Resolves a CLI task name against the configured workspace tasks.

root_dir()

Returns the normalized workspace root for the current Mix project.

root_dir(workspace_config)

Returns the normalized workspace root from a workspace config.

run!(task, args)

Runs a configured workspace task for the current Mix project.

run!(workspace_config, task, args)

Runs a configured workspace task.

split_runner_args(args)

Splits runner-level args from child task args.

task_args(workspace_config, task, extra_args \\ [])

Builds task args for a configured workspace task.

Types

runner_args()

@type runner_args() :: [String.t()]

stage()

@type stage() :: %{
  task: task_name(),
  commands: [Blitz.Command.t()],
  max_concurrency: pos_integer()
}

task_name()

@type task_name() :: atom()

workspace_config()

@type workspace_config() :: keyword() | map()

Functions

autodetect_multiplier(opts \\ [])

@spec autodetect_multiplier(keyword()) :: 1 | 2 | 3 | 4 | 6

Returns a recommended workspace multiplier for the current machine.

Auto mode uses the lower of a CPU-derived class and a memory-derived class so heavy Mix tasks do not scale only on one axis. Pass :schedulers_online and :memory_bytes to make detection deterministic in tests or custom tooling.

command_env(workspace_config, project_path, task)

@spec command_env(workspace_config(), String.t(), task_name()) :: [
  {String.t(), String.t() | nil}
]

Builds environment overrides for a project/task pair.

hashed_project_name(base_name, project_path, opts \\ [])

@spec hashed_project_name(String.t(), String.t(), keyword()) :: String.t()

Builds a stable hashed name for a workspace project path.

load!(project_config \\ Mix.Project.config())

Loads and normalizes workspace configuration from the current Mix project.

max_concurrency(workspace_config, task, runner_override \\ nil)

@spec max_concurrency(workspace_config(), task_name(), pos_integer() | nil) ::
  pos_integer()

Returns the effective concurrency for a workspace task.

package_paths()

@spec package_paths() :: [String.t()]

Returns workspace project paths excluding the root "." entry.

package_paths(workspace_config)

@spec package_paths(workspace_config()) :: [String.t()]

Returns workspace project paths excluding the root "." entry.

plan(workspace_config, task, args \\ [])

@spec plan(workspace_config(), task_name(), [String.t()]) :: [stage()]

Builds the staged execution plan for a workspace task.

project_paths()

@spec project_paths() :: [String.t()]

Returns workspace project paths in stable configured order.

project_paths(workspace_config)

@spec project_paths(workspace_config()) :: [String.t()]

Returns workspace project paths in stable configured order.

resolve_task_name!(workspace_config, task_name)

@spec resolve_task_name!(workspace_config(), String.t()) :: task_name()

Resolves a CLI task name against the configured workspace tasks.

root_dir()

@spec root_dir() :: String.t()

Returns the normalized workspace root for the current Mix project.

root_dir(workspace_config)

@spec root_dir(workspace_config()) :: String.t()

Returns the normalized workspace root from a workspace config.

run!(task, args)

@spec run!(task_name(), [String.t()]) :: :ok

Runs a configured workspace task for the current Mix project.

run!(workspace_config, task, args)

@spec run!(workspace_config(), task_name(), [String.t()]) :: :ok

Runs a configured workspace task.

split_runner_args(args)

@spec split_runner_args([String.t()]) :: {runner_args(), keyword()}

Splits runner-level args from child task args.

task_args(workspace_config, task, extra_args \\ [])

@spec task_args(workspace_config(), task_name(), [String.t()]) :: [String.t()]

Builds task args for a configured workspace task.