Strip the Header, Compare the Body

One Script, Two Modes

The whole enforcement mechanism is a single script with a flag. In deploy mode it walks a manifest and writes each kit source into each consumer's declared target path. In check mode it walks the same manifest and, instead of writing, compares — reporting every target whose body differs from its source, and every target that should exist and does not.

Using one program for both is not an economy measure; it is the correctness argument. If deploy and check were separate implementations, they could disagree about what "the expected content" is, and then the check would be verifying something the deploy never produces. Sharing the code path means the check is asking exactly the question the deploy answers.

Two Kinds of Failure, Reported Separately

Check mode distinguishes drifted from missing, and it is worth keeping them apart because they have different causes and different fixes. Drifted means the file is there and its body does not match — somebody edited a copy, or a deploy was never run after a kit change. Missing means the manifest says this consumer should have the file and it is not there — usually a new consumer added to a target list before the deploy ran.

Both fail, but the messages differ, and the message is where most of the value of a check lives. "Differs from the kit source" tells you to look at a diff. "The kit expects it vendored" tells you to run the deploy. Collapsing them into a generic failure would mean every incident starts with the same investigation.

The deploy and the check must be one implementation. Any verification written separately from the thing it verifies eventually drifts from it, and a check that has drifted from its subject is worse than no check — it produces confident green results about a question nobody is asking any more. When you build a verifier, look for the way to make it reuse the producer's own code path rather than reimplement it.

What This Buys at Review Time

There is a quieter benefit that shows up when reading someone else's change. In a consumer repository, a diff that touches a vendored file is immediately suspicious — the header says do not edit here, and the drift test would have caught it. So a reviewer does not need to know which files are shared: the header announces it, and the test enforces it.

That is the difference between a convention and a mechanism. A convention requires every reviewer to remember which files are off-limits. A mechanism means the reviewer can review the interesting part of the change and trust that the boring invariant is already held.

Code

Deploy and check, sharing one definition of 'expected'·python

def run(check: bool, only_repo: str | None = None) -> int:
    manifest = load_manifest()
    drifted: list[str] = []
    missing: list[str] = []
    deployed = unchanged = 0

    for entry in manifest["files"]:
        source = KIT_ROOT / entry["source"]
        raw = transform(source.read_text(), entry.get("transform"))

        for repo, target_rel in entry["targets"].items():
            if only_repo and repo != only_repo:
                continue
            repo_root = consumers[repo]
            if not repo_root.is_dir():
                # A sibling that is not checked out on this machine is
                # skipped, never failed. Cold clones must still work.
                print(f"consumer repo not found, skipping: {repo}")
                continue

            target = repo_root / target_rel
            # ONE definition of expected, used by both modes:
            expected_body = substitute(raw, entry.get("vars", {}).get(repo))
            expected_file = header_for(entry["source"], target, kit_sha) \
                + expected_body

            if check:
                if not target.is_file():
                    missing.append(f"{repo}:{target_rel}")     # different
                elif strip_header(target.read_text()) != expected_body:
                    drifted.append(f"{repo}:{target_rel}")     # causes
                continue

            if target.is_file() and \
                    strip_header(target.read_text()) == expected_body:
                unchanged += 1
                continue
            target.parent.mkdir(parents=True, exist_ok=True)
            target.write_text(expected_file)
            deployed += 1

    if check:
        for item in drifted:
            print(f"DRIFT: {item} differs from the kit source")
        for item in missing:
            print(f"MISSING: {item} (the kit expects it vendored)")
        return 1 if (drifted or missing) else 0

    print(f"{deployed} deployed, {unchanged} already current")
    return 0

Exercise

Take any pair of files in your world that are supposed to be identical — a config duplicated across environments, a schema mirrored in two services, a constants list in two languages. Write the twenty-line checker: read both, normalize the parts that are legitimately allowed to differ, compare the rest, print a message naming the remedy. Then wire it into whichever test suite the person most likely to break it actually runs.

Hint

The hard part is not the comparison, it is deciding what is legitimately allowed to differ. Write that list down explicitly in the checker rather than in your head — it is the actual specification of the relationship between the two files, and it is the thing a future reader will need.

One Script, Two Modes

Two Kinds of Failure, Reported Separately

What This Buys at Review Time

Code

External links

Exercise

Progress

Comments 0