Parallelmap

parallelmap

A test suite or a job pipeline takes as long as it takes — unless some of it can run side by side. parallelmap takes the workload graph — every job's name, its duration, and the names of the jobs that must finish before it starts — and maps out what can safely parallelize:

• Levels — the jobs grouped by depth. Level 0 holds the jobs with no dependencies; every other job sits at one level above its deepest dependency. Everything in a level can run together, once the levels below it are done.
• Sequential vs parallel time — the sum of all durations against the makespan with unbounded workers (the largest earliest finish), and the speedup between them. All reported seconds are rounded to 3 decimals, and the speedup is computed from those rounded values.
• Critical path — the chain that sets the parallel time, in execution order. Ties — for the finishing job and for each step back along the chain — go to the smallest job name, so the path is fully deterministic.
• Worker schedule — pass a worker count and a greedy list schedule assigns the jobs in (level, name) priority order, each to the worker that frees up first (lowest index on a tie), starting no earlier than its dependencies' finishes under that schedule. The schedule reports each job's worker, start, and finish, sorted by (start, worker, job), plus the resulting makespan. Without a worker count there is no schedule and the makespan is the unbounded parallel time.
• Cycle detection — when the jobs cannot be scheduled at all, parallelmap does not error out or guess. It reports ok: false with the exact cycle: a depth-first search over names and dependencies in ascending order returns the first cycle it finds as the list of jobs forming it (a job that depends on itself reports as a one-name cycle), with the time fields null.

The graph must be closed: a depends_on entry naming a job that was not supplied is a validation error, as are a missing or duplicate job name, a missing, negative, or non-finite duration, and a worker count that is not an integer of at least 1. Errors name the offending path (for example jobs[1].depends_on[0] references unknown job "build") and no partial map is produced. The computation is pure and local: no network, no configuration, no files read beyond the input you pass in.

CLI

npx @reneturcios/parallelmap map --input args.json

npx @reneturcios/parallelmap --version

args.json contains the full arguments object:

{

"jobs": [ { "name": "compile", "duration_seconds": 30 }, { "name": "unit", "duration_seconds": 45, "depends_on": ["compile"] }, { "name": "lint", "duration_seconds": 10, "depends_on": ["compile"] }, { "name": "package", "duration_seconds": 5, "depends_on": ["unit", "lint"] } ], "workers": 2 }

depends_on defaults to [] per job and workers is optional overall. The map is printed as JSON:

{

"ok": true, "levels": [["compile"], ["lint", "unit"], ["package"]], "sequential_seconds": 90, "parallel_seconds": 80, "speedup": 1.125, "critical_path": ["compile", "unit", "package"], "cycle": [], "schedule": [ { "job": "compile", "worker": 0, "start": 0, "finish": 30 }, { "job": "unit", "worker": 0, "start": 30, "finish": 75 }, { "job": "lint", "worker": 1, "start": 30, "finish": 40 }, { "job": "package", "worker": 1, "start": 75, "finish": 80 } ], "makespan_seconds": 80 }

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/parallelmap mcp

MCP client config:

{

"mcpServers": { "parallelmap": { "command": "npx", "args": ["-y", "@reneturcios/parallelmap", "mcp"] } } }

Tools

• map_parallelization — Map which jobs or tests can safely run in parallel.
• jobs (array, required, at least one) — jobs as {name, duration_seconds, depends_on?} objects; name is unique across the set and each depends_on entry names another supplied job
• workers (integer, optional, at least 1) — when given, a greedy schedule onto that many workers is included

Returns {ok, levels, sequential_seconds, parallel_seconds, speedup, critical_path, cycle, schedule, makespan_seconds} — or, on a cycle, {ok: false, cycle, levels: [], sequential_seconds, parallel_seconds: null, speedup: null, critical_path: [], schedule: [], makespan_seconds: null}.

Docker

docker run -i ghcr.io/cloudcorprecords/parallelmap

docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/parallelmap map --input /w/args.json

Development

npm install

npm run build # tsc -> dist/ npm test # tsx --test test/*.test.ts (pure local, no network) npm run dev # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios