Module walk 

Corpus file discovery — a byte-exact port of find_markdown_files (src/rac/core/fs.py) and the walk seam, per PORT-CONTRACT.d/09 §1.

Landmines reproduced here:

• Extension filter is the literal glob *.md, case-sensitive on Linux: upper.MD, x.Md, x.markdown do not match.
• Hidden exclusion: any component of the path relative to root that starts with . drops the path (hidden dirs at any depth, and hidden files). Equivalent to pruning hidden entries during the walk.
• Symlink asymmetry (Python 3.11 rglob): a symlinked file matching *.md IS yielded; a symlinked directory is NOT descended.
• Sort is component-wise (PurePath._cparts tuple), NOT whole-string: sub/c.md sorts before sub-x.md. We sort by the tuple of relative components, each compared by Unicode scalar (== UTF-8 byte order).

Structs

WalkEntry

One discovered markdown file.

Enums

WalkTarget

What a command should do with a positional path argument: validate/inspect and friends dispatch a single file directly, a directory through the walk.

Functions

dispatch

Classify a positional path argument for single-file vs directory dispatch.

find_markdown_files

Find *.md files under directory, dropping any path with a dotted component, in component-wise sorted order. recursive=false looks only at direct children (root.glob instead of root.rglob).

is_directory

True if path is a directory (the guard Path(arg).is_dir() used by stats/export/review before walking).

normalize_root

Normalize a directory argument the way str(Path(directory)) does (PurePosixPath semantics, PORT-CONTRACT.d/09 §1.6):

py_join

str(Path(root) / a / b / ...) — the normalized root joined with literal relative components (skill/hook install destination paths). Reuses the walk’s join_display semantics: a bare-. root vanishes, “/” and a preserved “//” prefix avoid doubled slashes.