# macOS metadata and source discovery

macOS can create AppleDouble companions whose path components start with `._`.
These files contain filesystem metadata and are not application source. On the
external-drive review checkout, the former Vitest include pattern selected
`src/avatar/._*.test.ts` files and attempted to transform their binary contents.
TypeScript 5.8 already skips the tested dot-prefixed paths with its existing
`src` include. Its new explicit exclusions document the same metadata policy
while preserving compiler options and ordinary input discovery.

Shared source issue [#11](https://git.whoagland.com/phenom/healer-man/issues/11)
owns the default discovery correction:

- `vite.config.ts` retains `configDefaults.exclude` and adds `**/._*` plus
  `**/._*/**` to the test exclusions.
- `tsconfig.app.json` retains its compiler options and `include: ["src"]`.
  Its exclusions retain the package-directory defaults and add the same
  metadata patterns.

The two patterns cover companion files and files inside a companion directory,
including nested directories. A component must start with `._`; ordinary
underscore names and names containing those characters elsewhere remain source.
Existing metadata files are retained. This changes root input discovery;
TypeScript's normal handling of explicit imports still applies.

`tools/verify-appledouble-metadata-discovery.mjs` supplies a focused regression
proof through actual Vitest discovery/execution and TypeScript configuration
input parsing. It uses fresh task-owned fixtures to verify the rejection path
and two ordinary test sentinels to verify continued execution. It does not certify
full application typechecking, a browser production build, gameplay, balance,
character rendering or dungeon behavior.

Exact commands, input identities and observed results accompany the issue and
`metadata-discovery-validation.json`. Shared source issue
[#9](https://git.whoagland.com/phenom/healer-man/issues/9) still owns its separate
browser build/live visual acceptance gap. Native checkpoint
[#292](https://git.whoagland.com/Codex/healer-man-godot/issues/292) is already
installed and merged. This tooling change requires no native runtime rebuild:
the native writable source mirror is a subset without these browser configs.

Run the focused proof after installing the repository dependencies:

```sh
node tools/verify-appledouble-metadata-discovery.mjs --evidence-dir /absolute/fresh-path
```

Use a fresh absolute path outside the checkout. The helper keeps its fixtures
and reports; it refuses existing destinations, overlap and symlink paths. It
works from another current directory and uses the Node executable that launched
it. The final external-drive control records three binary metadata transform
failures; fixed Vitest defaults run both ordinary tests. TypeScript API and CLI
resolve the same two ordinary inputs, with and without the explicit metadata
filters. The Vite/Node configuration typecheck passes.