feat(cgc): inspect D3D12 adapters and the MLIR patterns their drivers…

[Zac (tezheng)]

… declare

Two questions get asked on every new machine and after every driver update: which D3D12 adapters are here, and what does this driver's MLIR-program implementation claim it can match. Both are answered through public Windows APIs with ctypes, so nothing has to be built and no extra package installed.

winml cgc adapters # which adapters are here
winml cgc patterns [-a ADAPTER] [-v] # what a driver declares
winml cgc patterns -a ADAPTER --dump [--overwrite] # keep it on disk
winml cgc patterns [-a ADAPTER] --open [FILE] # look at a dump

Listing adapters needs nothing beyond Windows. Anything touching MLIR patterns needs an Agility SDK D3D12Core.dll of SDK 720 or newer, named by --d3d12-dir or $WINML_D3D12_DIR/$D3D12_DIR, or dropped in bin/ beside the venv or the install; the inbox runtime does not serve the preview feature. Which core answered opens every run on the redist: line, because the same driver reports different things through the 720 and 721 exchange shapes. When none can be found, the MLIR column reads ? rather than no -- the question could not be asked -- and the failure names every place that was searched.

With no -a, patterns asks every adapter and prints one line each; a driver that claims the exchange and then refuses it costs only its own line, on stderr, and the run exits 1 at the end. A -a number is an index when one exists and otherwise a description substring, so -a 5060 finds the RTX 5060.

A dump is filed under patterns/// and holds patterns.mlir, metadata.txt (the six keys dxcgc-dump-driver-patterns writes, plus which redist and ABI produced it and how the stored payload differs from the one received) and patterns.json: one record per pattern -- index, name, kind, benefit, rule count, source file, kernel, line count and its own text -- plus a summary, per-kind and per-source grouping and a format tag, so nothing downstream has to parse MLIR. Text payloads are normalised once, where the exchange returns them: the trailing NUL is dropped and every line break becomes LF, so the counts, patterns.mlir and patterns.json describe the same bytes. Bytecode is left alone.

Counting treats a pattern as one cgc_pattern.pattern declaration and a rule as one flat match alternative after any_of expansion, because comparing declaration counts alone across drivers can read a loss where the matching surface grew. Comments are blanked rather than deleted so offsets stay valid, the displayed text keeps its comments, and a brace inside a comment cannot unbalance a slice.

--open shows a dump in the CGC Pattern Atlas, a self-contained page that ships inside the package and is resolved with importlib.resources, so it works from a wheel, an editable install and a checkout alike. A dump is embedded into a copy of the page named after it, with every "<" escaped so a pattern's own text cannot close the script element. --open FILE shows a dump taken earlier and asks no driver anything; anything that is not a patterns.json is a usage error.

Verified on an RTX 5060 (driver 32.0.16.3004), an AMD 880M and WARP against the SDK 720 and 721 redists in DXCGC-Drop10.0-x64 and against Drop11: 51 patterns / 63 rules on the 720 path, byte-identical dumps across refactors, and the documented exit codes on every failure path. docs/commands/cgc.md covers both commands, every flag and scenario, the dump layout and patterns.json. TODO(tests) markers record the gaps left untested.