Hash the Output Tree Before You Extract One Helper

A messy repository does not require a complete rewrite to improve it. Instead, it needs a consistent output tree that serves as an oracle. Once you extract a pure helper function, stop there. However, AI diffing can produce tidy output, but it may still alter behavior. Cheap generation does not equate to cheap verification. A directory hash can catch drift before reviews are even conducted.

The issues often stem from scripts mixing I/O, scoring, and print statements. Callers rely on files, not function names. Internal unit tests often overlook these file contracts. A full rewrite typically moves all seams at once, making it difficult to determine which edit caused the tree to break. By focusing on one helper function and one hash, you can keep blame local to the change.

The oracle must lock only three facts on the first pass. These include the exit code after a fixture run, the relative paths of every produced file, and the SHA-256 digest of each produced file. Do not lock timestamps, PID strings, or the current working directory. Import graphs or private names should also remain unlocked, as they can change during a safe extraction.

Standard output can be deferred until the tree is stable. Logs can be noisy, but the files themselves are the true product. Start by hashing the files first, then consider pinning log entries. A messy script deserves to be pinned down. The example provided is a stocktake CLI that processes CSV files, scores rows based on various conditions, and writes the results in JSON format.

The scoring logic is intertwined with the I/O operations, creating the mess in the code. The script is named `stocktake.py` and is used as a characterization target rather than production advice. The key components include:

1. Importing necessary modules such as `csv`, `json`, `sys`, and `pathlib`.

2. Defining the `run` function that takes a list of command-line arguments and performs the main logic.

3. Checking if the correct number of arguments is provided and printing usage instructions if not.

4. Setting up the input and output directories based on the provided arguments.

5. Reading CSV files from the input directory, processing the data, and storing the results in a list of dictionaries.

6. Creating a JSON payload containing the count of rows and the list of processed items.

7. Writing the payload to a JSON file in the output directory.

8. Exiting the script with a success code if the `run` function returns 0.

The scoring rules dictate how the rows are processed, including handling special flags like 'haz' and 'bulk' that modify the score calculation. These rules should be nested within the main logic until the tree hash passes the verification process. The workflow consists of three numbered steps:

1. Build a tiny fixture tree using two CSV files and an empty output folder. Keep the data in an ugly format to accurately represent the real mess in the script. Commit this fixture to version control and never generate it later.

2. Run the script against the fixture directory, recording a golden tree that represents the expected output. Hash each file under the output directory and store the manifest alongside the fixture.

3. Compare the actual output with the golden tree by running the script again and hashing the resulting files. Store the resulting hash in a file named `golden.sha256` next to the fixture.

By following these steps and focusing on one helper function and one hash, you can maintain a clean and verifiable codebase even when dealing with a messy repository.