fix(compile): address codemod-refactor PR review

Two findings + two suggestions from the latest Rust PR Reviewer pass:

1. Naming clash in `perform_source_rewrite_if_needed`: the
   parameter `codemods: &codemods::CodemodReport` shadowed the
   sibling `codemods` module. Functionally fine (the module isn't
   used inside the function body) but a future caller adding a
   `codemods::something()` reference would hit a confusing type
   error. Renamed to `report`.

2. `docs/codemods.md` claimed "Front-matter key order is preserved"
   without qualification. Renamed keys move to the END of the
   front-matter block because `Mapping::insert` appends new keys
   when absent. Updated the doc to call this out, and added the
   same note to the stderr warning emitted when codemods rewrite
   the source.

3. Marked the two registry-health tests
   (`registry_ids_are_unique`, `codemod_filenames_match_registry_count`)
   as vacuously true while CODEMODS is empty, so future reviewers
   don't mistake the green test for a meaningful invariant today.

4. Added a comment on the `pub use helpers::*` re-export and on
   the helper-level `#[allow(dead_code)]`s explaining they're
   defensive against the empty-registry warning surface and should
   be stripped once the first real codemod lands.

Plus, while in the docs, added an "unsanitized input" invariant
to the codemod author contract: the runner sanitizes the typed
`FrontMatter` AFTER codemods run, so the raw `Mapping` codemods
receive is whatever the user wrote. Codemods should treat values
as opaque rather than parse/interpolate them.

All 1349 tests pass. No behavior changes outside the docs and the
warning text.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jamesadevine

docs/codemods.md

@@ -43,8 +43,13 @@ every compile; codemods that don't match are essentially free.
   the closing `---`).
 - **Leading whitespace** before the opening `---` is preserved
   byte-for-byte (BOM-strippers and editor blank lines).
-- **Front-matter key order** is preserved by `serde_yaml`'s
-  insertion-ordered mapping.
+- **Front-matter key order** is preserved for keys the codemod
+  doesn't touch (`serde_yaml`'s mapping is insertion-ordered).
+  Renamed keys, however, move to the **end** of the front-matter
+  block: `Mapping::insert` appends new keys, so when a codemod
+  removes `old-key` and inserts `new-key`, the new key lands at
+  the bottom regardless of where the old one was. The compile
+  warning calls this out so users aren't surprised.
 - **Front-matter comments** are NOT preserved. `serde_yaml`
   round-trip drops them. The warning emitted on rewrite calls this
   out so it isn't a surprise. If you have important context in a
@@ -191,6 +196,15 @@ review + per-codemod tests:
 6. **Order-aware.** If codemod B depends on shapes produced by
    codemod A, A must precede B in the registry. Document the
    ordering requirement in B's doc comment.
+7. **Receives unsanitized input.** The compiler runs sanitization
+   (`##vso[` neutralization, control-character stripping, length
+   limits) on the typed `FrontMatter` *after* codemods run, but the
+   raw `Mapping` you receive is whatever the user wrote — including
+   any pipeline-injection attempts, control characters, or
+   over-length strings. Codemods should therefore treat values as
+   opaque (move them around, wrap them in objects, etc.) rather
+   than parse or interpolate them. If a codemod must inspect a
+   value, treat it defensively.
 
 ### Use the helpers
 

src/compile/codemods/mod.rs

@@ -33,6 +33,13 @@ use anyhow::{Context, Result};
 use serde_yaml::Mapping;
 
 mod helpers;
+// `#[allow(unused_imports)]` here mirrors the per-item
+// `#[allow(dead_code)]` annotations in `helpers.rs`. While the
+// CODEMODS registry is empty, no in-crate caller exercises these
+// re-exports — the lint warns. Once the first real codemod lands
+// and uses one of these helpers, both the re-export attribute and
+// the per-item `dead_code` allows on `helpers.rs` should be
+// removed.
 #[allow(unused_imports)]
 pub use helpers::{insert_no_overwrite, rename_key, take_key, ConflictPolicy};
 
@@ -159,6 +166,9 @@ mod tests {
 
     #[test]
     fn registry_ids_are_unique() {
+        // Vacuously true while CODEMODS is empty; the assertion
+        // machinery still compiles so this test guards against
+        // duplicate ids the moment a real codemod ships.
         let mut seen = std::collections::BTreeSet::new();
         for c in CODEMODS {
             assert!(
@@ -171,8 +181,10 @@ mod tests {
 
     #[test]
     fn codemod_filenames_match_registry_count() {
-        // Scan src/compile/codemods/*.rs and check that each numeric
-        // codemod file is present exactly once in the registry.
+        // Vacuously true while CODEMODS is empty (the directory
+        // contains only `mod.rs` and `helpers.rs`, which are
+        // skipped). Once a numeric `<NNNN>_<id>.rs` file lands, this
+        // test asserts the registry was updated to match.
         let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
             .join("src/compile/codemods");
         let mut numeric_files: Vec<String> = Vec::new();

src/compile/mod.rs

@@ -263,7 +263,7 @@ async fn perform_source_rewrite_if_needed(
     front_matter_mapping: &serde_yaml::Mapping,
     body_raw: &str,
     source_sha256: &[u8; 32],
-    codemods: &codemods::CodemodReport,
+    report: &codemods::CodemodReport,
 ) -> Result<bool> {
     let new_content =
         common::reconstruct_source(leading_whitespace, front_matter_mapping, body_raw)?;
@@ -303,11 +303,12 @@ async fn perform_source_rewrite_if_needed(
         })?;
 
     eprintln!("warning: applied codemods to {}:", input_path.display());
-    for applied in &codemods.applied {
+    for applied in &report.applied {
         eprintln!("  - {}: {}", applied.id, applied.summary);
     }
     eprintln!(
-        "note: front-matter comments are not preserved when codemods rewrite the source."
+        "note: front-matter comments are not preserved when codemods rewrite the source. \
+         Renamed keys may move to the end of the front-matter block."
     );
 
     Ok(true)