wuf 0.1.0a7__tar.gz

wuf-0.1.0a7/.github/scripts/sync_lock_version.py

@@ -0,0 +1,123 @@
+"""Synchronize Wuf's release version into committed release metadata."""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import tempfile
+import tomllib
+from pathlib import Path
+
+from packaging.version import InvalidVersion, Version
+
+_VERSION_LINE = re.compile(r'version = "[^"]+"(?P<newline>\r?\n)?\Z')
+_COMPATIBILITY_DEPENDENCIES_LINE = re.compile(
+    r'^dependencies = \["wuf[^"]*"\](?P<newline>\r?\n)?$',
+    re.MULTILINE,
+)
+
+
+def synchronize_version(repository: Path, requested_version: str) -> None:
+    """Update the editable lock entry and Workfold compatibility requirement."""
+
+    try:
+        normalized = str(Version(requested_version))
+    except InvalidVersion as error:
+        raise ValueError(f"invalid release version: {requested_version!r}") from error
+
+    pyproject_path = repository / "pyproject.toml"
+    lock_path = repository / "uv.lock"
+    project = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    configured = str(project["project"]["version"])
+    if Version(configured) != Version(normalized):
+        raise ValueError(f"release version {normalized!r} does not match pyproject.toml version {configured!r}")
+
+    _synchronize_compatibility_requirement(repository, normalized)
+
+    lines = lock_path.read_text(encoding="utf-8").splitlines(keepends=True)
+    matching_blocks = _editable_project_blocks(lines)
+    if len(matching_blocks) != 1:
+        raise ValueError(f"expected one editable wuf package in uv.lock, found {len(matching_blocks)}")
+    start, end = matching_blocks[0]
+    version_indexes = tuple(index for index in range(start, end) if _VERSION_LINE.fullmatch(lines[index]) is not None)
+    if len(version_indexes) != 1:
+        raise ValueError("editable wuf package must contain exactly one version in uv.lock")
+
+    index = version_indexes[0]
+    newline = "\r\n" if lines[index].endswith("\r\n") else "\n"
+    replacement = f'version = "{normalized}"{newline}'
+    if lines[index] != replacement:
+        lines[index] = replacement
+        _atomic_write(lock_path, "".join(lines))
+
+    locked = tomllib.loads(lock_path.read_text(encoding="utf-8"))
+    packages = tuple(
+        package
+        for package in locked.get("package", ())
+        if package.get("name") == "wuf" and package.get("source") == {"editable": "."}
+    )
+    if len(packages) != 1 or Version(str(packages[0].get("version"))) != Version(normalized):
+        raise RuntimeError("uv.lock version synchronization did not validate")
+
+
+def _synchronize_compatibility_requirement(repository: Path, normalized: str) -> None:
+    compatibility_path = repository / "compat" / "workfold" / "pyproject.toml"
+    content = compatibility_path.read_text(encoding="utf-8")
+    project = tomllib.loads(content)
+    configured = str(project["project"]["version"])
+    if Version(configured) != Version(normalized):
+        raise ValueError(f"release version {normalized!r} does not match compatibility package version {configured!r}")
+
+    matches = tuple(_COMPATIBILITY_DEPENDENCIES_LINE.finditer(content))
+    if len(matches) != 1:
+        raise ValueError(f"expected one Wuf compatibility dependency, found {len(matches)}")
+    match = matches[0]
+    newline = match.group("newline") or ""
+    replacement = f'dependencies = ["wuf=={normalized}"]{newline}'
+    if match.group(0) != replacement:
+        content = content[: match.start()] + replacement + content[match.end() :]
+        _atomic_write(compatibility_path, content)
+
+    synchronized = tomllib.loads(compatibility_path.read_text(encoding="utf-8"))
+    dependencies = synchronized["project"].get("dependencies", ())
+    if dependencies != [f"wuf=={normalized}"]:
+        raise RuntimeError("Workfold compatibility dependency synchronization did not validate")
+
+
+def _editable_project_blocks(lines: list[str]) -> tuple[tuple[int, int], ...]:
+    starts = [index for index, line in enumerate(lines) if line.rstrip("\r\n") == "[[package]]"]
+    blocks: list[tuple[int, int]] = []
+    for ordinal, start in enumerate(starts):
+        end = starts[ordinal + 1] if ordinal + 1 < len(starts) else len(lines)
+        content = {line.rstrip("\r\n") for line in lines[start:end]}
+        if 'name = "wuf"' in content and 'source = { editable = "." }' in content:
+            blocks.append((start, end))
+    return tuple(blocks)
+
+
+def _atomic_write(path: Path, content: str) -> None:
+    mode = path.stat().st_mode
+    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+    temporary = Path(temporary_name)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as stream:
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.chmod(temporary, mode)
+        os.replace(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = sys.argv[1:] if argv is None else argv
+    if len(arguments) != 1:
+        raise SystemExit("usage: sync_lock_version.py VERSION")
+    synchronize_version(Path(__file__).resolve().parents[2], arguments[0])
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wuf-0.1.0a7/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jan T. Müller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wuf-0.1.0a7/MANIFEST.in

@@ -0,0 +1,4 @@
+recursive-include tests *.py
+recursive-include benchmarks *.py *.md
+include .github/scripts/sync_lock_version.py
+include THIRD_PARTY_NOTICES.md

wuf-0.1.0a7/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: wuf
+Version: 0.1.0a7
+Summary: Unify local Git and filesystem timestamp footprints in a representative weekly activity view.
+Author-email: "Jan T. Müller" <mail@jantmueller.com>
+License-Expression: MIT
+Project-URL: homepage, https://github.com/janthmueller/wuf
+Project-URL: documentation, https://janthmueller.github.io/wuf/
+Project-URL: source, https://github.com/janthmueller/wuf
+Project-URL: tracker, https://github.com/janthmueller/wuf/issues
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pathspec<2,>=1
+Requires-Dist: rich<15,>=14.3
+Requires-Dist: tzdata>=2025.2; sys_platform == "win32"
+Requires-Dist: tzlocal<6,>=5
+Provides-Extra: audit
+Requires-Dist: pip-audit<3,>=2.9; extra == "audit"
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=6; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Provides-Extra: release
+Requires-Dist: build>=1; extra == "release"
+Requires-Dist: pyinstaller>=6; extra == "release"
+Requires-Dist: python-semantic-release<11,>=10; extra == "release"
+Requires-Dist: twine>=5; extra == "release"
+Dynamic: license-file
+
+# Wuf
+
+[![PyPI Latest Release](https://img.shields.io/pypi/v/wuf.svg)](https://pypi.org/project/wuf/)
+[![Pepy Total Downloads](https://img.shields.io/pepy/dt/wuf)](https://pepy.tech/project/wuf)
+[![GitHub License](https://img.shields.io/github/license/janthmueller/wuf)](https://github.com/janthmueller/wuf/blob/main/LICENSE)
+
+**WUF Unifies Footprints.**
+
+Wuf folds local Git and filesystem timestamp footprints onto one representative
+Monday-to-Sunday week. It highlights activity outside your intended working
+hours without pretending that timestamped events are hours worked.
+
+![Wuf terminal output](https://raw.githubusercontent.com/janthmueller/wuf/main/docs/public/wuf-output.svg)
+
+Wuf is local, private by design, terminal-only, and currently alpha.
+
+## Install
+
+```bash
+pip install wuf
+wuf --help
+```
+
+For an isolated installation, use `uv tool install wuf` or
+`pipx install wuf`. Standalone binaries are available from
+[GitHub releases](https://github.com/janthmueller/wuf/releases).
+
+### Renamed from Workfold
+
+Wuf is the continuation of Workfold under its shorter, permanent name. Wuf
+packages also install `workfold` as a compatibility command, but `wuf` is the
+canonical command going forward. Existing configuration should be renamed from
+`workfold.toml` to `wuf.toml`, and `[tool.workfold]` tables should become
+`[tool.wuf]`.
+
+## Quick start
+
+Run `wuf` inside a Git repository to see the current ISO week:
+
+```bash
+wuf
+```
+
+The selectors you will use most are:
+
+```bash
+wuf . -t 2w3d                    # rolling elapsed window
+wuf . -t 2026-W31                # one ISO week
+wuf . -p fs                      # current filesystem metadata
+wuf . -p both                    # low-noise Git + filesystem view
+wuf . -p portable -t all         # evidence stored in Git objects
+wuf . -p full -t all --git-commits-from all-refs --include-ignored
+wuf . -e git:tag:tagger fs:file:modified
+```
+
+They control separate parts of the request:
+
+| Selector | Purpose | Values |
+| --- | --- | --- |
+| `-t`, `--time` | Date scope | `this-week`, `2w3d`, `YYYY-Www`, `DATE..DATE`, `all` |
+| `-p`, `--profile` | Named event set | `git`, `fs`, `both`, `portable`, `full` |
+| `-e`, `--events` | Exact event set (alternative to a profile) | IDs and wildcards |
+
+The profiles answer different questions:
+
+- `git`: What does ordinary commit activity look like? This is the default.
+- `fs`: What birth and modification metadata exists for current regular files?
+- `both`: What does the combined low-noise Git and filesystem pattern look like?
+- `portable`: What dated evidence is stored inside Git objects?
+- `full`: Which timestamps exist across every supported Git and filesystem event kind?
+
+Profiles expand only to event sets. Time, Git reachability, ignored files, and
+explicit exclusions remain independently configurable.
+
+For exact control, `-e/--events` accepts identifiers such as
+`git:commit:author`, `git:tag:tagger`, and `fs:file:modified`; quote wildcards
+such as `'git:*'`. `-l/--list` appends bounded event details. Paths must appear
+before either space-separated selector, or after an option-terminating `--`.
+
+Schedules support daily intervals, breaks, overnight shifts, and `all`:
+
+```bash
+wuf . --hours 'Mo-Thu 08:00-16:30; Fr 08:00-14:00'
+wuf . --hours 'Mo-Fr 22:00-06:00'
+wuf . --hours all
+```
+
+See the [usage guide](https://janthmueller.github.io/wuf/guides/usage/)
+for clustering, fixed bands, identity markers, day hiding, grids, exact event
+selection, configuration, and every CLI option.
+
+## Configuration
+
+Put personal defaults in the platform configuration directory, or project
+defaults in `wuf.toml`:
+
+```toml
+timezone = "Europe/Berlin"
+hours = "Mo-Thu 08:00-16:30; Fr 08:00-14:00"
+profile = "portable"
+cluster-anchor = "midnight"
+band-label = "start"
+show-empty-bands = true
+count-grouping = "visual"
+grid = "vertical"
+hide-empty-days = ["weekend"]
+
+[styles."git:tag:*"]
+symbol = "◆"
+color = "magenta"
+outside-symbol = "◇"
+outside-color = "bright_red"
+```
+
+Python projects may use `[tool.wuf]` in `pyproject.toml` instead. Values
+resolve as built-in → global → nearest project → CLI. Inspect the result and
+each value's origin without collecting timestamps:
+
+```bash
+wuf . --show-config
+```
+
+Use `--config FILE` for one exact file or `--no-config` for built-ins plus CLI
+only. The [usage guide](https://janthmueller.github.io/wuf/guides/usage/#configuration-files)
+documents locations, discovery, merging, and every supported key.
+
+## Reading the chart
+
+- By default, circles are Git events and squares are filesystem events.
+- Default green/blue filled markers are inside the schedule; red hollow markers
+  are outside. Colorless output preserves the shape distinction, and event
+  style rules may replace both symbol pairs and their colors.
+- One symbol is one event; busy cells use exact `×N` counts. Counts stay
+  separate per event kind by default; `--count-grouping visual` merges kinds
+  only when their resolved symbol and configured color match.
+- Empty time is compressed, and `⋮` reports a meaningful gap.
+- Identity-marker mode replaces Git circles with codes mapped in the key.
+- Event-selector style rules can replace source-marker symbols and colors while
+  keeping collection and coverage unchanged.
+
+The summary independently splits all events by schedule and by calendar day.
+Weekend events can therefore also be outside working hours.
+
+## Accuracy and privacy
+
+- Events are discrete timestamp observations, not work sessions or duration.
+- Collection is local: Wuf does not contact a Git host or telemetry service.
+- Git history can be rewritten; reflogs can expire; filesystem metadata is a
+  mutable snapshot and birth time depends on platform and filesystem support.
+- Coverage reports unavailable, unsupported, and unreadable evidence that can
+  prevent a complete answer. Known timestamps outside the requested time or
+  identity scope are not counted as coverage outcomes.
+
+See the [documentation](https://janthmueller.github.io/wuf/) for every CLI
+option, collector semantics, coverage guarantees, and platform notes.
+
+## Development
+
+The Python package lives directly in `wuf/`; there is no `src/` wrapper.
+
+```bash
+nix develop
+uv sync --locked --extra dev
+uv run --locked pytest
+uv run --locked ruff check .
+uv run --locked ruff format --check .
+uv run --locked pyright
+```
+
+Use `nix run .#docs-dev` for the documentation site and
+`nix run .#docs-check` to validate it. The
+[architecture guide](https://janthmueller.github.io/wuf/reference/architecture/)
+documents the package boundaries, dependency rules, data pipeline, and test
+layout.

wuf-0.1.0a7/README.md

@@ -0,0 +1,174 @@
+# Wuf
+
+[![PyPI Latest Release](https://img.shields.io/pypi/v/wuf.svg)](https://pypi.org/project/wuf/)
+[![Pepy Total Downloads](https://img.shields.io/pepy/dt/wuf)](https://pepy.tech/project/wuf)
+[![GitHub License](https://img.shields.io/github/license/janthmueller/wuf)](https://github.com/janthmueller/wuf/blob/main/LICENSE)
+
+**WUF Unifies Footprints.**
+
+Wuf folds local Git and filesystem timestamp footprints onto one representative
+Monday-to-Sunday week. It highlights activity outside your intended working
+hours without pretending that timestamped events are hours worked.
+
+![Wuf terminal output](https://raw.githubusercontent.com/janthmueller/wuf/main/docs/public/wuf-output.svg)
+
+Wuf is local, private by design, terminal-only, and currently alpha.
+
+## Install
+
+```bash
+pip install wuf
+wuf --help
+```
+
+For an isolated installation, use `uv tool install wuf` or
+`pipx install wuf`. Standalone binaries are available from
+[GitHub releases](https://github.com/janthmueller/wuf/releases).
+
+### Renamed from Workfold
+
+Wuf is the continuation of Workfold under its shorter, permanent name. Wuf
+packages also install `workfold` as a compatibility command, but `wuf` is the
+canonical command going forward. Existing configuration should be renamed from
+`workfold.toml` to `wuf.toml`, and `[tool.workfold]` tables should become
+`[tool.wuf]`.
+
+## Quick start
+
+Run `wuf` inside a Git repository to see the current ISO week:
+
+```bash
+wuf
+```
+
+The selectors you will use most are:
+
+```bash
+wuf . -t 2w3d                    # rolling elapsed window
+wuf . -t 2026-W31                # one ISO week
+wuf . -p fs                      # current filesystem metadata
+wuf . -p both                    # low-noise Git + filesystem view
+wuf . -p portable -t all         # evidence stored in Git objects
+wuf . -p full -t all --git-commits-from all-refs --include-ignored
+wuf . -e git:tag:tagger fs:file:modified
+```
+
+They control separate parts of the request:
+
+| Selector | Purpose | Values |
+| --- | --- | --- |
+| `-t`, `--time` | Date scope | `this-week`, `2w3d`, `YYYY-Www`, `DATE..DATE`, `all` |
+| `-p`, `--profile` | Named event set | `git`, `fs`, `both`, `portable`, `full` |
+| `-e`, `--events` | Exact event set (alternative to a profile) | IDs and wildcards |
+
+The profiles answer different questions:
+
+- `git`: What does ordinary commit activity look like? This is the default.
+- `fs`: What birth and modification metadata exists for current regular files?
+- `both`: What does the combined low-noise Git and filesystem pattern look like?
+- `portable`: What dated evidence is stored inside Git objects?
+- `full`: Which timestamps exist across every supported Git and filesystem event kind?
+
+Profiles expand only to event sets. Time, Git reachability, ignored files, and
+explicit exclusions remain independently configurable.
+
+For exact control, `-e/--events` accepts identifiers such as
+`git:commit:author`, `git:tag:tagger`, and `fs:file:modified`; quote wildcards
+such as `'git:*'`. `-l/--list` appends bounded event details. Paths must appear
+before either space-separated selector, or after an option-terminating `--`.
+
+Schedules support daily intervals, breaks, overnight shifts, and `all`:
+
+```bash
+wuf . --hours 'Mo-Thu 08:00-16:30; Fr 08:00-14:00'
+wuf . --hours 'Mo-Fr 22:00-06:00'
+wuf . --hours all
+```
+
+See the [usage guide](https://janthmueller.github.io/wuf/guides/usage/)
+for clustering, fixed bands, identity markers, day hiding, grids, exact event
+selection, configuration, and every CLI option.
+
+## Configuration
+
+Put personal defaults in the platform configuration directory, or project
+defaults in `wuf.toml`:
+
+```toml
+timezone = "Europe/Berlin"
+hours = "Mo-Thu 08:00-16:30; Fr 08:00-14:00"
+profile = "portable"
+cluster-anchor = "midnight"
+band-label = "start"
+show-empty-bands = true
+count-grouping = "visual"
+grid = "vertical"
+hide-empty-days = ["weekend"]
+
+[styles."git:tag:*"]
+symbol = "◆"
+color = "magenta"
+outside-symbol = "◇"
+outside-color = "bright_red"
+```
+
+Python projects may use `[tool.wuf]` in `pyproject.toml` instead. Values
+resolve as built-in → global → nearest project → CLI. Inspect the result and
+each value's origin without collecting timestamps:
+
+```bash
+wuf . --show-config
+```
+
+Use `--config FILE` for one exact file or `--no-config` for built-ins plus CLI
+only. The [usage guide](https://janthmueller.github.io/wuf/guides/usage/#configuration-files)
+documents locations, discovery, merging, and every supported key.
+
+## Reading the chart
+
+- By default, circles are Git events and squares are filesystem events.
+- Default green/blue filled markers are inside the schedule; red hollow markers
+  are outside. Colorless output preserves the shape distinction, and event
+  style rules may replace both symbol pairs and their colors.
+- One symbol is one event; busy cells use exact `×N` counts. Counts stay
+  separate per event kind by default; `--count-grouping visual` merges kinds
+  only when their resolved symbol and configured color match.
+- Empty time is compressed, and `⋮` reports a meaningful gap.
+- Identity-marker mode replaces Git circles with codes mapped in the key.
+- Event-selector style rules can replace source-marker symbols and colors while
+  keeping collection and coverage unchanged.
+
+The summary independently splits all events by schedule and by calendar day.
+Weekend events can therefore also be outside working hours.
+
+## Accuracy and privacy
+
+- Events are discrete timestamp observations, not work sessions or duration.
+- Collection is local: Wuf does not contact a Git host or telemetry service.
+- Git history can be rewritten; reflogs can expire; filesystem metadata is a
+  mutable snapshot and birth time depends on platform and filesystem support.
+- Coverage reports unavailable, unsupported, and unreadable evidence that can
+  prevent a complete answer. Known timestamps outside the requested time or
+  identity scope are not counted as coverage outcomes.
+
+See the [documentation](https://janthmueller.github.io/wuf/) for every CLI
+option, collector semantics, coverage guarantees, and platform notes.
+
+## Development
+
+The Python package lives directly in `wuf/`; there is no `src/` wrapper.
+
+```bash
+nix develop
+uv sync --locked --extra dev
+uv run --locked pytest
+uv run --locked ruff check .
+uv run --locked ruff format --check .
+uv run --locked pyright
+```
+
+Use `nix run .#docs-dev` for the documentation site and
+`nix run .#docs-check` to validate it. The
+[architecture guide](https://janthmueller.github.io/wuf/reference/architecture/)
+documents the package boundaries, dependency rules, data pipeline, and test
+layout.

wuf-0.1.0a7/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# Third-party notices for standalone Wuf bundles
+
+The standalone archives are produced with PyInstaller and include portions of
+the Python runtime plus Wuf's runtime dependencies. Their exact license
+files are copied into the archive's `licenses/` directory at build time.
+
+- Python and its standard library: Python Software Foundation License.
+- pathspec: Mozilla Public License 2.0.
+- Rich: MIT License.
+- markdown-it-py and mdurl: MIT License.
+- Pygments: BSD 2-Clause License.
+- tzlocal: MIT License.
+- tzdata, when bundled on Windows: licenses shipped by the Python tzdata
+  distribution and the underlying IANA time-zone database.
+- PyInstaller bootloader: GNU General Public License with PyInstaller's
+  bootloader exception; its shipped notices are included.
+
+This notice is informational. The complete license texts included beside the
+binary control the corresponding components.

wuf-0.1.0a7/benchmarks/README.md

@@ -0,0 +1,87 @@
+# Wuf benchmarks
+
+These are opt-in end-to-end measurements, not ordinary correctness tests. A
+benchmark starts a complete Wuf process and includes configuration,
+collection, folding, terminal rendering, and the local Git subprocesses it
+uses.
+
+## Run a suite
+
+From the repository root:
+
+```bash
+uv run python -m benchmarks.run ~/linux --suite quick
+uv run python -m benchmarks.run ~/linux --suite scope --json benchmarks/results/linux.json
+uv run python -m benchmarks.run --fixture medium --suite complete
+```
+
+The built-in suites are:
+
+- `quick`: low-noise Git, filesystem, and combined current-week profiles;
+- `scope`: those three profiles for both current-week and all-date selection;
+- `profiles`: deliberately broad portable and full workloads with bounded and
+  all-date selections; Git cases use all locally stored refs and filesystem
+  cases include ignored entries where applicable;
+- `complete`: every named case.
+
+Repeat `--case NAME` to select an exact subset instead. Run `--help` for the
+case names and process controls. `--wuf-executable PATH` measures an
+installed script or release binary instead of `python -m wuf` from the
+checkout.
+
+## Measurements
+
+Each recorded sample includes:
+
+- monotonic wall time;
+- child user and system CPU time where the platform exposes it;
+- the Wuf process's kernel-recorded high-water RSS on Linux;
+- sampled peak RSS summed across the Wuf process tree on Linux;
+- minor and major page faults and voluntary/involuntary context switches;
+- exit status, timeout state, stdout/stderr sizes, and a stdout digest;
+- the exact `Events` summary count.
+
+Every workload adds `--strict`, so incomplete collection fails instead of
+becoming a successful timing sample. The runner also rejects missing summaries,
+changed event counts, or changed stdout across repetitions. Raw JSON records Python, Wuf, Git,
+OS, CPU, load, total memory, Wuf checkout revision/dirty state, target
+HEAD/tracked dirty state, all-ref commit count, Git object-store statistics,
+commands, cache policy, and every individual sample.
+
+Main RSS is the stable high-water mark for Wuf itself. Summed tree RSS also
+captures concurrently running Git children, but it is not proportional-set
+size: shared pages can appear in more than one process. Sampling defaults to 5
+ms, so extremely short-lived child peaks can be missed. Non-Linux hosts report
+memory as `n/a`; timing and output validation still work.
+
+Warmups are explicit and the runner never drops the operating system's page
+cache. Compare results only under the same host, target, command, sample
+interval, and warmup policy. Do not use fixed cross-machine timing thresholds
+in the normal test workflow. Global and system Git configuration are disabled
+for repeatability; repository-local configuration still applies.
+
+## Synthetic fixtures
+
+`--fixture small|medium|directory-heavy|large` creates an automatically removed repository with
+historical and current-week commits, distinct author/committer identities,
+annotated tags, reflogs, tracked files, untracked files, ignored files,
+directories, and symlinks where supported.
+
+The `directory-heavy` fixture places one tracked, untracked, or ignored file in
+each directory. It isolates directory traversal and parent-handle validation
+costs that file-dense fixtures can hide:
+
+```bash
+uv run python -m benchmarks.run --fixture directory-heavy --case fs-all
+```
+
+To keep a fixture for profiling tools, create one explicitly in a new or empty
+directory:
+
+```bash
+uv run python -m benchmarks.fixture /tmp/wuf-medium --size medium
+uv run python -m benchmarks.run /tmp/wuf-medium --suite complete
+```
+
+Fixture generation refuses non-empty targets and never deletes an existing
+repository.

wuf-0.1.0a7/benchmarks/__init__.py

@@ -0,0 +1 @@
+"""Opt-in end-to-end performance benchmarks for Wuf."""