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.