refactor: spell control characters as escapes, and lint for raw ones - #29948

Linked issue

n/a — nothing filed. Say the word if you'd rather talk the check over first.

Summary

Two files hold a control character as a raw byte where an escape was meant. Same string at runtime, so nothing misbehaves. The cost is all in the tooling around the code.

packages/2-sql/1-core/contract/src/validators.ts separates the halves of a (tableName, name) key with a NUL. Git reads a file containing a NUL as binary, so GitHub shows no diff for 1100 lines of validation logic, and blame, log -S and grep skip it.

packages/1-framework/3-tooling/emitter/test/domain-type-generation.test.ts has a raw BEL in a test input. That test is about escaping control characters, every neighbouring line writes its own character as an escape, and the expectation on the same line asks for the escaped form — so the intent isn't in question.

The separator itself is a good idea and a house pattern. schema-diff.ts has SIBLING_KEY_DELIMITER, psl-field-resolution.ts has MODEL_COORDINATE_SEPARATOR, migration-graph.ts spells out the reasoning in a comment: no identifier can contain a NUL, so ("a_b", "c") can never collide with ("a", "b_c"). Only the spelling was off.

The second commit adds pnpm lint:control-bytes so nobody has to catch this by eye next time.

Testing performed

Finding them meant scanning all 6711 tracked files byte by byte. Git's own binary flag wasn't enough — it only reads the first 8000 bytes, so a NUL further down a long file never shows up.

• pnpm lint:control-bytes against the pre-fix files exits 1 and names both, with line and byte; on the fixed tree it exits 0
• node --test scripts/lint-control-bytes.test.mjs — 7 cases: NUL, the rest of the C0 range, an already-escaped character, tab/LF/CR, binary formats, and both exit codes
• pnpm test:scripts — 395 tests, 371 pass. Without this branch it's 388/364 with the same 24 failures, so nothing here adds one. Those 24 are path-separator assertions in unrelated scripts that only fail on Windows
• pnpm --filter @internal/emitter test 208/208 and pnpm --filter @internal/sql-contract test 322/322, plus typecheck and lint on both
• pnpm lint:workflows after adding the CI step

git ls-files --eol now calls validators.ts i/lf, where it was i/-text. It's a text file again.

Skill update

n/a — internal tooling, plus two literals rewritten to the same value.

Checklist

• All commits are signed off (git commit -s) per the DCO.
• I read CONTRIBUTING.md and the change is scoped to one logical concern.
• Tests are updated.
• The PR title is a conventional commit (per CONTRIBUTING.md for external contributors).
• The Skill update section above is filled in.

Notes for the reviewer

The check skips binaries by file extension rather than by sniffing content, which is the one call worth arguing about. A NUL byte is what makes a file look binary in the first place, so sniffing would skip exactly the files this is meant to find. The cost is that a new binary format has to be added to the list, and until it is the check complains instead of going quiet. I'd rather have it that way round, but it's your call.

It also only looks at tracked files, so a violation in a file you haven't added yet is invisible. I walked into that myself while writing it: the script picked up a raw NUL in its own doc comment and reported the tree clean, because it wasn't tracked. CI runs against a commit, so everything is tracked there.

In validators.ts I named a constant instead of inlining the escape, following the two sites that already do that. Both styles exist in the tree, so switch me if you prefer the inline one.

Two commits, literals first and the check second, so you can drop the CI step without losing the fix.

Summary by CodeRabbit

• New Features

  • Added a new validation check to catch raw control characters in source files during CI.
  • Added a command to run this check locally from the package scripts.

• Bug Fixes

  • Improved handling of escaped control characters in serialization tests, keeping output unchanged.

• Tests

  • Added coverage for detecting raw control bytes, reporting file/line details, and ignoring binary or whitespace-safe cases.