A Copy With a Birth Certificate

A File That Says Where It Came From

The single most important property of a vendored copy is that a reader who opens it — six months later, in a repository they have never worked in, hunting a bug — immediately knows three things: this file is not authored here, here is where it is authored, and here is what to run to change it.

So every deployed file gets a first line. It names the kit source path, the kit commit the body came from, and the instruction:

GENERATED FROM the-kit/kit/python/kit_pippa.py @ <kit-sha> — DO NOT EDIT HERE. Edit the kit and run the sync script.

The comment syntax is chosen per file extension, which is a small detail with a large consequence: the header is a comment in Python, TypeScript, JavaScript, CSS and Swift alike, so one deploy mechanism can serve every language in the family without any of them needing a preamble stripped at build time.

Why the Header Must Not Be Compared

The header names the kit commit that was current when the file was deployed. The file on disk does not churn — a re-deploy only rewrites a copy whose body actually changed. But the expected header is built from the kit's HEAD right now, so the moment the kit commits anything at all, every already-deployed file carries a SHA older than the one a comparison would compute. Include the header in that comparison and every consumer reports drift after every kit commit, forever, for files nobody touched.

A check that fires constantly is a check that gets disabled. So the comparison strips the first line if it carries the marker, and compares only what follows. Drift then means exactly one thing: the body differs. That precision is what lets the check be wired into test suites without anybody resenting it.

Separate the metadata that changes from the content that matters, or your check will cry wolf. This shows up far beyond vendoring: generated timestamps in build artifacts, commit hashes in version files, dates in headers. Any comparison over content that has volatile metadata embedded in it will produce noise, the noise will be normalized, and the signal will be lost. Put the volatile part where the comparison cannot see it.

The Awkward Case: Refreshing Only the Certificate

There is one wrinkle worth knowing, because it is the kind of thing that looks like a bug in the tool. Sometimes a consumer's tests must pass before the kit change is committed — so the deploy runs first, and the header it writes names the kit's previous commit. The body is right; the certificate is one commit stale.

The tool handles that with a narrow, explicit mode: after the kit commits, re-run the deploy with an instruction to refresh provenance for the named sources only. It rewrites those headers and touches nothing else — so unrelated vendored files keep the commit that actually deployed their body, which is the honest record. It is a small feature, and it exists because the alternative (blanket header rewrites) would quietly destroy the one piece of information the header is for.

Code

The header: written per language, stripped before comparison·python

HEADER_MARK = "GENERATED FROM the-kit"

# One deploy mechanism, every language in the family. The header has
# to be a COMMENT in the target language or the file will not parse.
COMMENT_STYLES = {
    ".py":    ("# ", ""),
    ".ts":    ("// ", ""),
    ".tsx":   ("// ", ""),
    ".js":    ("// ", ""),
    ".css":   ("/* ", " */"),   # CSS needs a closing delimiter
    ".swift": ("// ", ""),
}


def header_for(source_rel: str, target: Path, sha: str) -> str:
    prefix, suffix = COMMENT_STYLES.get(target.suffix, ("# ", ""))
    return (
        f"{prefix}{HEADER_MARK}/{source_rel} @ {sha} - DO NOT EDIT HERE. "
        f"Edit the kit and run the sync script.{suffix}\n"
    )


def strip_header(text: str) -> str:
    """Remove the provenance line before comparing bodies.

    Guarded on the MARKER, not on 'is line 1 a comment'. A kit file may
    legitimately open with a comment of its own; only a line carrying
    the marker is ours to drop.
    """
    lines = text.splitlines(keepends=True)
    if lines and HEADER_MARK in lines[0]:
        return "".join(lines[1:])
    return text


# Deploy: header + body. Compare: body only.
expected_body = source_text
expected_file = header_for(source_rel, target, kit_sha) + expected_body

actual = target.read_text()
is_drifted = strip_header(actual) != expected_body      # <- the body

# The header question is only meaningful INSIDE the body-matches arm.
# Asked on its own it is true whenever `is_drifted` is true, so it
# would not be cosmetic at all - it would just be drift, reported
# twice under two names.
needs_refresh = (not is_drifted) and actual != expected_file
#
# Two DIFFERENT questions, and the nesting is what keeps them apart.
# `is_drifted` fails a test suite. `needs_refresh` is cosmetic, and
# is only acted on when a deploy explicitly asks for it.

Exercise

Find a generated file in a project you work on — a schema binding, an API client, a lockfile-adjacent artifact — and check whether it says where it came from and how to regenerate it. If it does not, add a one-line header with both. Then check whether any comparison, diff review, or test in the project would be confused by that header, and make sure it is excluded from the comparison rather than from the file.

Hint

The interesting failure is a header that names a timestamp instead of a source revision. A timestamp changes on every regeneration, so the file churns even when nothing changed, and reviewers learn to skip the diff — which is the opposite of what provenance is for.

A File That Says Where It Came From

Why the Header Must Not Be Compared

The Awkward Case: Refreshing Only the Certificate

Code

External links

Exercise

Progress

Comments 0