An auto tiler for macOS
parcel Scripts Names.md
5.4 kB · 93 lines
Markdown
at main

Naming guard #

make lint checks tracked working files and paths, commit bodies reachable from all refs (including branches and checkpoints), available Mach-O executables and libraries under build/ and .build/, and Packaging/background.png. Binary text comes from strings; dependency caches and compiler intermediates are not products. Discovery skips intermediate and symbol directories and checks file type and permissions before opening candidates. Binary scanning avoids per-fragment file reads. Use --artifact PATH for a product built elsewhere. Missing optional build directories are fine; unreadable inputs, failed tools, and malformed policy files fail the check.

mise run setup installs tools and lefthook for this worktree only. For installed tools, Scripts/setup.sh --hooks-only just installs hooks. It enables Git's worktree-specific configuration, migrates the old naming-hook path, and refuses to replace foreign hooks. pre-commit checks staged changes; commit-msg also checks the proposed message and requires a DCO sign-off (git commit -s). The pre-push check includes the full naming scan. No cryptographic signing, app launch, or private input is needed. A newly initialized empty repository needs one whole-file commit before partial staging; lefthook otherwise refuses to hide the unstaged changes. Ordinary clones are unaffected.

--staged reads only changed index blobs plus the indexed policy and allowlist, in one git cat-file --batch process. It never substitutes unstaged policy edits. Deleted paths, unchanged files, commit history, and local build artifacts are left for the full check. Policy and allowlist contents are still checked on an empty index diff, and missing or malformed indexed inputs fail closed. Staged binaries are checked as content; a proposed --commit-msg is checked even with no staged changes. Use --artifact PATH with a full check, not with --staged.

Updating the policy #

Keep one name per line in $PARCEL_NAMES_FILE, which defaults to ~/.config/parcel-dev/blocked-names.txt, then run:

Scripts/generate-name-hashes.sh

The generator accepts only single tokens and token pairs and refuses private inputs inside the repository. For the first generation, or to change which names need product context, pass --context-file /absolute/private/contextual-names.txt containing that subset, one per line. Otherwise regeneration preserves the existing salt and context-only classifications. --names-file and --hashes override the input and output paths. Never commit either private input file.

The checked-in policy holds a random 128-bit salt and SHA-256 digests of bytes(salt) + NUL + lowercase(tokens joined by one space). It contains no name spellings. This is a spelling guard, not encryption: a public salt does not make a small dictionary secret.

Tokens are complete Unicode alphanumeric words; identifiers are not split at capital letters. Pairs can span whitespace or path punctuation. Context-only matches need capitalization, adjacent product language, or a path, URL, or bundle identifier. Unquoted member access is not a bundle identifier.

Binary output uses printable runs of at least four bytes. Names shorter than four characters also need adjacent product language or a path, URL, or bundle identifier; capitalization and NUL termination alone are not evidence in machine code or compressed pixels. Standalone short binary labels are intentionally not checked, but the same text in source is still checked. Debug binaries omit the local checkout prefix from the scan, not the paths relative to it. The guard does not OCR image pixels or mount compressed disk images.

Reviewing an exception #

Scripts/check-names.sh --json
Scripts/check-names.sh --report-allowed
mise exec -- swift test --filter NameGuardTests

Inspect each reported location before adding an entry to name-allowlist.json. Copy its scope, line_hash, and token_hash, then add a short reason without the spelling. For content, paths, and commits, also copy source_hash: these exceptions must stay source-scoped. Artifact exceptions omit source_hash so the same compiled string is allowed in debug, release, either build system, app bundles, and explicitly supplied products. They never allow source text, paths, commit messages, other strings, or other tokens on the same line. Existing source-scoped artifact entries remain supported when that narrower scope is useful.

Source paths are hashed too, so an exception cannot reintroduce a spelling through its filename. The source hash covers source + NUL + exact source path; the line hash covers allow + NUL + trimmed exact line, both with the same salted digest. A pair crossing lines includes all those lines. Artifact sources in lowercase SwiftPM debug/release directories omit the target-triple directory for existing source-scoped entries. New text invalidates an exception; indentation does not. --report-allowed shows the hits actually used, including deliberate ordinary-word exceptions. --json includes the fingerprints, allowed hits, and artifact count. Exit status is 0 for clean, 1 for a policy violation, and 2 for a checking error.

The Swift Testing suite lives in Scripts/tests/NameGuardTests and uses throwaway repositories and a generated policy of invented names, never the private list.