Before counting files, define the scan boundary

A number needs a boundary

A project directory may include source code, dependencies, caches and earlier reports. Adding their lengths is easy; explaining what the total means takes a clear scope.

The updated script accepts exact root-relative exclusions. Excluding node_modules does not exclude frontend/node_modules: the latter needs its own entry. This keeps the rule predictable and visible in the report.

Two small bugs that change the result

The old summary used (root files) as the root-file bucket while allowing real directory names as other keys. A directory with that exact name would merge into the bucket. Version 2 prefixes directory keys with ./ and keeps the root bucket separate.

Writing the report inside the scanned tree also means the next scan can count the old report. The CLI now rejects that output location before scanning. Existing destinations are still protected by exclusive creation.

Keep an example small enough to check by hand

The shared fixture has five files of 4, 12, 8, 16 and 32 bytes. The 32-byte file is in node_modules. Excluding that directory leaves four files and 40 bytes; a 10-byte threshold selects two files.

The Python sample creates those files in a temporary directory. The web page uses the same fixture to explain filtering; it does not scan the visitor’s computer.

python examples/make_sample.py
python -m unittest discover -s tests -v

Forty bytes is a synthetic teaching total, not a storage-saving result.

Test decisions, including the failures

Local Python 3.12 ran 15 tests: 14 passed and the real-symlink test was skipped because this host does not allow creating symlinks. A simulated Windows reparse attribute check passed. Cross-platform CI has its own execution logs.

• Use equal-size files to check tie ordering. A different directory enumeration should not rearrange the report.
• Simulate an unreadable directory. Keep the readable results and record the missing path instead of pretending the scan was complete.
• Reject a negative, zero or non-finite threshold before output is created.
• Keep existing output and source file bytes unchanged when an operation is refused.

What I would not infer from this report

Logical lengths differ from allocated disk space. Hardlinks are counted by path; compressed and sparse files have other storage behavior. The report also omits excluded paths and links.

A changing filesystem is not an atomic snapshot. Stable sorting improves comparison, but does not prove that two scans saw the same files at the same moment.

The lesson I want to retain is to write the scope and failure behavior beside a result. Even a small utility can demonstrate engineering judgment through clear inputs, reproducible examples and explicit limits.