feat(rfc_tools): enforce Git LFS tracking for media assets

[jtmcdole]

RFC media assets (such as screenshots) must be tracked via Git LFS (Large File Storage). Committed raw binary blobs permanently bloat Git history, even when deleted in subsequent commits.

• Added Git LFS Configuration via .gitattributes using case-insensitive bracket globs (*.[pP][nN][gG], etc.), mapped to filter=lfs.
• When users checkout the LFS files (smudge), this check uses git lfs fsck --pointers directly against Git revision trees in the object database, eliminating false positives from smudged working-copy binaries and avoiding temp-file disk I/O.
• lfs-verify.yml with inline GitHub Actions error annotations (::error file=...::) and remediation instructions.

Flow:

flowchart TD
    A["bin/lfs_verify.dart"] --> B["LfsVerifier.verify()"]
    B --> C{"Check Prerequisites"}
    C -->|"git-lfs missing"| Err["Fail Fast: Exit 1<br/>(Prompt 'git lfs install')"]
    C -->|"git-lfs present"| D{"Execution Mode"}

    D -->|"--base-branch (PR Mode)"| E["verifyPullRequest()"]
    D -->|"Default (Trunk Mode)"| F["verifyTrackedFiles()"]

    E --> G["git diff -z --name-only<br/>(Extracts PR-modified paths)"]
    G --> J{"Audit Scope"}
    F --> M["git lfs fsck --pointers HEAD<br/>(All tracked files)"]

    J -->|"Default PR Mode (Squash)"| K["git lfs fsck --pointers HEAD<br/>(Scoped to PR-modified files)"]
    J -->|"--audit-intermediate-commits"| L["git lfs fsck --pointers mergeBase..HEAD<br/>(Scoped to PR-modified files)"]

    K & L & M --> N["parseFsckOutput()<br/>(Extracts file path & diagnostic detail)"]
    N --> O["LfsVerificationResult<br/>(isSuccess, issues, checkedCount)"]
    O -->|"Issues Detected"| P["GitHub Actions Annotations<br/>::error file=...::<br/>& Actionable Remediation Guidance"]
    O -->|"Zero Issues"| Q["Exit 0: Verification Passed"]

Loading

[jtmcdole]

cleanup: sharing logging and process runner across other binaries, testing.

[jtmcdole]

cleanup for process runner sharing

[jtmcdole]

this is the source of truth for what should be placed into gitlfs.

[jtmcdole]

dropped any magic around fetch-depth because it was breaking assumptions. this isn't going to be a big tree, so silly optimization gone.

[jtmcdole]

ditto: we need the full checkout.

[jtmcdole]

I know what you're about to say "Codefu, this looks like you're adding an image" but I'm not:

❯ git cat-file -p HEAD:rfc/media/flutter_header.png
version https://git-lfs.github.com/spec/v1
oid sha256:9a14b0db34e1622cd3b2120f2661caaea7319992d1d15e10848764f653e8fc1e
size 6749

❯ git lfs ls-files
9a14b0db34 * rfc/media/flutter_header.png

Which is exactly why I wanted this action.

[jtmcdole]

also

[eyebrowsoffire]

LGTM!

[zanderso]

.gitattributes seems to contain both an allowlist of file name extensions that are presumed to be text, and a denylist of file name extensions that are presumed to be binary. Does the LfsVerifier fail if a file is not on the allowlist? Or does it fail if a file is on the denylist?

Either way, instead of using file name extensions, can you just ask grep instead, and if grep says that it's a binary file it has to be in lfs?

[jtmcdole]

.gitattributes is more of an enforcement about what we require in lfs, not an allowlist vs denylist!

Does the LfsVerifier fail if a file is not on the allowlist

Correct, if you write "foo.xyz" and its 10mb, I'm relying on the reviewers to say "Hey, don't do that".

can you just ask grep instead

Works if you're on a linux or mac machine, doesn't work if you are on a windows machine. Wouldn't be a bad thing if it was in the workflow file, but this is a dart util. Grep is still going to be brittle because I think its only using some simple heuristics (does the file contain NUL bytes or maybe some control characters...) or we could use file --mime-type <file>.

I'm not banning binary files. I'm requesting they are put in LFS. If someone tries to add a base64 encoded png to a document or file.