ci: have the generator declare which paths it owns, and check it wrote them

.github/actions/codegen-declaration/action.yml

@@ -0,0 +1,15 @@
+name: codegen-declaration
+description: >-
+  Fails `rainix-copy-artifacts` when a codegen hook declared a generated path it then did not write. Re-running the generators and diffing proves the committed CONTENT is current, but a generator that has STOPPED emitting a file writes nothing, so the already-correct committed copy is left alone, nothing differs and the job is green over a dead emitter (rainlanguage/rain.factory.deploy#35). Only the generator knows which paths it owns rather than deliberately leaves frozen, so it declares them on stdout — `rainix-codegen owns <path>` and `rainix-codegen wrote <path>` — and the workflow tees that into the log this reads. A repo whose hooks declare nothing is a no-op.
+runs:
+  using: composite
+  steps:
+    - name: Check the codegen declaration
+      shell: bash
+      run: |
+        set -euo pipefail
+        # path: ref runs the check from THIS composite's own checkout, so the
+        # check version always matches the action version (same pattern as
+        # mutation-ledger) regardless of any RAINIX_SHA the caller pins.
+        nix run "path:$(cd "$GITHUB_ACTION_PATH/../../.." && pwd)#rainix-static" -- \
+          codegen-declaration --log "$RUNNER_TEMP/rainix-codegen.log"

.github/workflows/rainix-copy-artifacts.yaml

@@ -26,33 +26,48 @@ jobs:
       # committed file has drifted from its source. The build-meta.sh hook is
       # consumer-supplied because rain meta build's invocation (input/output
       # filenames, meta type) varies per repo.
+      #
+      # Each hook's stdout is teed into one log: a hook may declare there which
+      # generated paths it owns and which it wrote, which is the half of the
+      # currency check the diff cannot do (codegen-declaration, below).
+      # `pipefail` is set in every teed step — bash otherwise reports `tee`'s
+      # exit status, so a failing generator would pass.
       - name: Regenerate meta artifacts
         if: hashFiles('script/build-meta.sh') != ''
-        run: nix develop github:rainlanguage/rainix/${{ env.RAINIX_SHA }}#sol-shell -c ./script/build-meta.sh
+        run: |
+          set -euo pipefail
+          nix develop github:rainlanguage/rainix/${{ env.RAINIX_SHA }}#sol-shell -c ./script/build-meta.sh | tee -a "$RUNNER_TEMP/rainix-codegen.log"
       # Committed generated sources must be regenerable here, or the currency
       # check below passes without checking anything. The codegen script is
       # `script/Build.sol`, matched exactly: a repo that renames or drops it
       # goes red rather than skipping regeneration and reporting green.
       - name: Regenerate generated sources
         run: |
+          set -euo pipefail
           if [ -d src/generated ] && [ ! -f script/Build.sol ]; then
             echo "::error::src/generated/ is committed but script/Build.sol was not found, so the committed sources cannot be currency checked here. The codegen script must be script/Build.sol."
             exit 1
           fi
           if [ -f script/Build.sol ]; then
-            nix develop github:rainlanguage/rainix/${{ env.RAINIX_SHA }}#sol-shell -c forge script ./script/Build.sol
+            nix develop github:rainlanguage/rainix/${{ env.RAINIX_SHA }}#sol-shell -c forge script ./script/Build.sol | tee -a "$RUNNER_TEMP/rainix-codegen.log"
           fi
       - name: Build Solidity
         run: nix develop github:rainlanguage/rainix/${{ env.RAINIX_SHA }}#sol-shell -c forge build
       - name: Copy forge artifacts into committed location
         if: hashFiles('script/CopyArtifacts.sol') != ''
-        run: nix develop github:rainlanguage/rainix/${{ env.RAINIX_SHA }}#sol-shell -c forge script ./script/CopyArtifacts.sol --ffi
+        run: |
+          set -euo pipefail
+          nix develop github:rainlanguage/rainix/${{ env.RAINIX_SHA }}#sol-shell -c forge script ./script/CopyArtifacts.sol --ffi | tee -a "$RUNNER_TEMP/rainix-codegen.log"
       # Catch-all post-forge regen hook: consumer-supplied. Runs outside any
       # nix devshell so the script picks shells per command (subgraph-shell,
       # sol-shell, etc.) for whatever derived artifacts it emits.
       - name: Regenerate derived artifacts
         if: hashFiles('script/build.sh') != ''
-        run: ./script/build.sh
+        run: |
+          set -euo pipefail
+          ./script/build.sh | tee -a "$RUNNER_TEMP/rainix-codegen.log"
+      - name: Assert every declared generated path was written
+        uses: rainlanguage/rainix/.github/actions/codegen-declaration@main
       - name: Format (so generated artifacts match committed style)
         run: nix develop github:rainlanguage/rainix/${{ env.RAINIX_SHA }}#sol-shell -c forge fmt
       - name: Assert committed artifacts match freshly built

README.md

@@ -163,6 +163,24 @@ single job it runs whichever of these the repo has:
 
 then `forge fmt` and the `git diff` assert.
 
+The diff answers "is the committed **content** current". It cannot answer "is
+anything still generating it": a generator that has stopped emitting a file
+writes nothing, the already-correct committed copy is left alone, and the job is
+green over a dead emitter (rainlanguage/rain.factory.deploy#35). Only the
+generator knows which paths it owns, as against a `src/generated/<tag>/`
+snapshot deliberately frozen forever — so the generator says so, on stdout:
+
+```
+rainix-codegen owns src/lib/LibReleasedSuites.sol
+rainix-codegen wrote src/lib/LibReleasedSuites.sol
+```
+
+The job tees every hook's stdout into one log and fails, naming the path, on
+anything declared `owns` that no hook then `wrote`. Nothing is declared by hand
+and no repo maintains a list: the same code that computes where to write emits
+these lines. A repo whose hooks print neither keeps exactly today's behaviour —
+green, with a note that a dead emitter there is still invisible.
+
 ```yaml
 name: copy-artifacts
 on: [push]

flake.nix

@@ -474,13 +474,15 @@
             bats test/bats/action/prompt-cap.test.bats
             bats test/bats/action/frozen-snapshots-append-only.test.bats
             bats test/bats/action/mutation-ledger.test.bats
+            bats test/bats/action/codegen-declaration.test.bats
             bats test/bats/task/skip-simulation.test.bats
             bats test/bats/task/subgraph-build.test.bats
             bats test/bats/task/subgraph-deploy-version.test.bats
             bats test/bats/task/sol-single-contract.test.bats
             bats test/bats/task/no-custom-natspec.test.bats
             bats test/bats/workflow/rainix-sol-static.test.bats
             bats test/bats/workflow/rainix-rs-static.test.bats
+            bats test/bats/workflow/rainix-copy-artifacts.test.bats
             bats test/bats/workflow/test-yml.test.bats
           '';
           additionalBuildInputs = [ pkgs.bats ] ++ sol-build-inputs ++ node-build-inputs;

rainix-static/src/codegen_declaration.rs

@@ -0,0 +1,200 @@
+use std::collections::BTreeSet;
+use std::path::Path;
+
+/// Line prefix a codegen hook prints to declare a path. `forge script` indents
+/// `console.log` output under `== Logs ==`, so lines are matched trimmed.
+pub(crate) const SENTINEL: &str = "rainix-codegen ";
+
+#[derive(Default, PartialEq, Eq, Debug)]
+pub(crate) struct Declaration {
+    pub(crate) owns: BTreeSet<String>,
+    pub(crate) wrote: BTreeSet<String>,
+    pub(crate) malformed: Vec<String>,
+}
+
+pub(crate) fn parse(log: &str) -> Declaration {
+    let mut out = Declaration::default();
+    for line in log.lines() {
+        let Some(rest) = line.trim().strip_prefix(SENTINEL) else {
+            continue;
+        };
+        match rest.split_once(char::is_whitespace) {
+            Some(("owns", path)) if !path.trim().is_empty() => {
+                out.owns.insert(path.trim().to_string());
+            }
+            Some(("wrote", path)) if !path.trim().is_empty() => {
+                out.wrote.insert(path.trim().to_string());
+            }
+            // Fail-closed: a verb this check does not know is a declaration it
+            // is silently not making, which is the defect one level up.
+            _ => out.malformed.push(line.trim().to_string()),
+        }
+    }
+    out
+}
+
+pub(crate) fn offences(
+    owns: &BTreeSet<String>,
+    wrote: &BTreeSet<String>,
+    present: &BTreeSet<String>,
+) -> Vec<String> {
+    let mut out = Vec::new();
+    for path in owns {
+        match (wrote.contains(path), present.contains(path)) {
+            (false, true) => out.push(format!(
+                "the codegen hooks declare {path} generated, but nothing wrote it on this run. \
+                 The committed copy is left exactly as it was, so regenerating and diffing \
+                 passes without ever checking it — its emitter is dead. Restore the emitter, or \
+                 stop declaring the path if it is genuinely no longer generated."
+            )),
+            (false, false) => out.push(format!(
+                "the codegen hooks declare {path} generated, but nothing wrote it and no such \
+                 file exists after the run."
+            )),
+            (true, false) => out.push(format!(
+                "a codegen hook reported writing {path}, but no such file exists after the run."
+            )),
+            (true, true) => {}
+        }
+    }
+    out
+}
+
+pub(crate) fn run(root: &Path, log: &Path) {
+    let text = match std::fs::read_to_string(log) {
+        Ok(text) => text,
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => String::new(),
+        Err(e) => crate::fail(&format!(
+            "codegen-declaration: failed to read {}: {e}",
+            log.display()
+        )),
+    };
+    let declaration = parse(&text);
+
+    if !declaration.malformed.is_empty() {
+        for line in &declaration.malformed {
+            eprintln!("::error::codegen-declaration: unreadable declaration: {line}");
+        }
+        std::process::exit(1);
+    }
+
+    if declaration.owns.is_empty() {
+        println!(
+            "codegen-declaration: clean — this repo's codegen declares no generated paths, so \
+             nothing here can tell a live emitter from one that has died"
+        );
+        return;
+    }
+
+    let present: BTreeSet<String> = declaration
+        .owns
+        .union(&declaration.wrote)
+        .filter(|path| root.join(path).exists())
+        .cloned()
+        .collect();
+    let offences = offences(&declaration.owns, &declaration.wrote, &present);
+
+    if !offences.is_empty() {
+        for line in &offences {
+            eprintln!("::error::codegen-declaration: {line}");
+        }
+        std::process::exit(1);
+    }
+
+    println!(
+        "codegen-declaration: clean — {} declared generated paths, each written this run",
+        declaration.owns.len()
+    );
+    for path in declaration.wrote.difference(&declaration.owns) {
+        println!("codegen-declaration: note — {path} was written but not declared, so nothing will notice if its emitter dies");
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn set(paths: &[&str]) -> BTreeSet<String> {
+        paths.iter().map(|p| p.to_string()).collect()
+    }
+
+    #[test]
+    fn forge_indented_lines_parse_into_both_sets() {
+        let log = "== Logs ==\n  rainix-codegen owns src/a.sol\n  rainix-codegen wrote src/a.sol\n";
+        let d = parse(log);
+        assert_eq!(d.owns, set(&["src/a.sol"]));
+        assert_eq!(d.wrote, set(&["src/a.sol"]));
+        assert!(d.malformed.is_empty());
+    }
+
+    #[test]
+    fn a_line_that_merely_mentions_the_sentinel_is_not_a_declaration() {
+        let d = parse("error: expected `rainix-codegen owns src/a.sol`\n");
+        assert_eq!(d, Declaration::default());
+    }
+
+    #[test]
+    fn repeated_declarations_of_one_path_are_one_path() {
+        let d = parse("rainix-codegen wrote src/a.sol\nrainix-codegen wrote src/a.sol\n");
+        assert_eq!(d.wrote, set(&["src/a.sol"]));
+    }
+
+    #[test]
+    fn an_unknown_verb_is_malformed_rather_than_ignored() {
+        let d = parse("rainix-codegen skipped src/a.sol\n");
+        assert_eq!(d.malformed, vec!["rainix-codegen skipped src/a.sol"]);
+    }
+
+    #[test]
+    fn a_verb_with_no_path_is_malformed() {
+        let d = parse("rainix-codegen owns\nrainix-codegen wrote   \n");
+        assert_eq!(d.malformed.len(), 2);
+        assert!(d.owns.is_empty());
+        assert!(d.wrote.is_empty());
+    }
+
+    #[test]
+    fn a_declared_path_nothing_wrote_is_an_offence_though_it_is_on_disk() {
+        let owns = set(&["src/lib/LibReleasedSuites.sol", "src/generated/A.sol"]);
+        let wrote = set(&["src/generated/A.sol"]);
+        let off = offences(&owns, &wrote, &owns);
+        assert_eq!(off.len(), 1);
+        assert!(off[0].contains("src/lib/LibReleasedSuites.sol"));
+        assert!(off[0].contains("emitter is dead"));
+    }
+
+    #[test]
+    fn a_declared_path_that_is_not_on_disk_says_so_instead() {
+        let owns = set(&["src/generated/Gone.sol"]);
+        let off = offences(&owns, &BTreeSet::new(), &BTreeSet::new());
+        assert_eq!(off.len(), 1);
+        assert!(off[0].contains("no such file exists"));
+    }
+
+    #[test]
+    fn a_path_reported_written_that_is_not_on_disk_is_an_offence() {
+        let all = set(&["src/a.sol"]);
+        let off = offences(&all, &all, &BTreeSet::new());
+        assert_eq!(off.len(), 1);
+        assert!(off[0].contains("reported writing"));
+    }
+
+    #[test]
+    fn every_declared_path_written_is_clean() {
+        let all = set(&["src/a.sol", "src/b.sol"]);
+        assert!(offences(&all, &all, &all).is_empty());
+    }
+
+    #[test]
+    fn a_written_but_undeclared_path_is_not_an_offence() {
+        let owns = set(&["src/a.sol"]);
+        let wrote = set(&["src/a.sol", "soldeer.lock"]);
+        assert!(offences(&owns, &wrote, &wrote).is_empty());
+    }
+
+    #[test]
+    fn declaring_nothing_is_not_an_offence() {
+        let wrote = set(&["src/a.sol"]);
+        assert!(offences(&BTreeSet::new(), &wrote, &wrote).is_empty());
+    }
+}

rainix-static/src/main.rs

@@ -34,6 +34,14 @@
 //       Nothing is stripped: a shell script reads the bytes on disk. Which
 //       files are prompts and what they may weigh is per-repo, so both are an
 //       input, and a glob matching nothing is an error rather than a pass.
+//   codegen-declaration --log <file> [--root <dir>]
+//       fail if a codegen hook declared a generated path it then did not
+//       write. Re-running the generators and diffing proves the committed
+//       CONTENT is current but is blind to a generator that has STOPPED
+//       emitting a file, and only the generator knows which paths it owns
+//       rather than deliberately leaves frozen. Hooks declare on stdout as
+//       `rainix-codegen owns <path>` and `rainix-codegen wrote <path>`, which
+//       the workflow tees into <file>. A repo declaring nothing passes.
 //   snapshots-append-only [--base <ref>] [--root <dir>]
 //       fail if the branch modifies or deletes an existing per-tag deploy-pin
 //       snapshot under <root>/<tag>/ (default root src/generated, base
@@ -96,6 +104,7 @@
 
 mod agent_context_cap;
 mod ci_gate;
+mod codegen_declaration;
 mod context_bytes;
 mod frozen_snapshots;
 mod mutation_ledger;
@@ -212,6 +221,12 @@ fn main() {
                 .unwrap_or_else(|| fail("soldeer-gate: --package <name> required"));
             soldeer_gate::run(&pkg, flag(&args, "--github-output").as_deref());
         }
+        "codegen-declaration" => {
+            let root = flag(&args, "--root").unwrap_or_else(|| ".".to_string());
+            let log = flag(&args, "--log")
+                .unwrap_or_else(|| fail("codegen-declaration: --log <file> required"));
+            codegen_declaration::run(Path::new(&root), Path::new(&log));
+        }
         "snapshots-append-only" => {
             let base = flag(&args, "--base").unwrap_or_else(|| "origin/main".to_string());
             let root = flag(&args, "--root").unwrap_or_else(|| "src/generated".to_string());
@@ -272,8 +287,8 @@ fn main() {
             eprintln!(
                 "rainix-static: unknown subcommand {other:?} \
                  (available: no-submodules, agent-context-cap, prompt-cap, \
-                 snapshots-append-only, mutation-ledger, ci-gate, soldeer-gate, \
-                 rpc-preflight, release-guard)"
+                 codegen-declaration, snapshots-append-only, mutation-ledger, \
+                 ci-gate, soldeer-gate, rpc-preflight, release-guard)"
             );
             std::process::exit(2);
         }