Skip to content

README.md

Latest commit

 

History

History
66 lines (43 loc) · 2.13 KB

README.md

File metadata and controls

66 lines (43 loc) · 2.13 KB
Raw

SideEffectMap

See what a command actually changed—not what it claimed it changed.

SideEffectMap snapshots a directory, runs one command without a shell, snapshots again, and emits a deterministic map of created, modified, and deleted files.

30-second demo

python -m pip install -e .
sideeffectmap run --root . -- python examples/write_demo.py

The JSON report includes:

  • command exit code, duration, timeout state, stdout, and stderr;
  • before/after hashes, sizes, and modes for every changed file;
  • a compact change summary;
  • an effects_sha256 fingerprint for comparison across runs.

Useful patterns

Audit a formatter:

sideeffectmap run --root . --output formatter-effects.json -- ruff format .

Fail CI if a supposedly read-only command writes anything:

sideeffectmap run --root . --fail-on-change -- python scripts/inspect.py

Ignore generated paths:

sideeffectmap run --root . --exclude coverage --exclude '*.log' -- npm test

Exit codes preserve the wrapped command's exit code. 10 means --fail-on-change found a write; 124 means timeout; 2 means invalid input.

Why it is different

  • Black-box measurement works with scripts, CLIs, build tools, and agent tools.
  • shell=False: the command is executed as the argument vector shown in the report.
  • Small files are content-hashed; large files are still tracked by size and mode.
  • Common dependency and VCS directories are ignored by default.
  • No runtime dependencies and no daemon.

Scope

Version 0.1 measures regular-file changes beneath the selected root. It does not claim to trace network calls, kernel activity, registry writes, or files outside that root. Run untrusted commands inside a real sandbox; SideEffectMap is an observer, not containment.

Development

python -m pip install -e .
python -m unittest discover -s tests -v

Project origin

Created and maintained by SamAlpha1. The canonical origin is SamAlpha1/SideEffectMap; see .provenance/origin.json, NOTICE, and the immutable Git history.

MIT licensed. Copies must preserve the copyright and license notice.