Rocky Codegen

Rocky codegen cascade

Rocky's CLI --output json is the interface contract with every consumer (Dagster, VS Code, shell scripts). Every command is backed by a typed Rust struct that derives JsonSchema, and the Pydantic + TypeScript bindings are autogenerated from those schemas. Drift is enforced in CI.

If you edit a Rust output struct and forget to regenerate, the codegen-drift workflow will fail the PR.

When to use this skill

• Editing a *Output struct in engine/crates/rocky-cli/src/output.rs or engine/crates/rocky-cli/src/commands/doctor.rs
• Adding a new field to any type that appears inside a CLI output
• Adding a brand new CLI command that needs a JSON schema
• Investigating a codegen-drift.yml CI failure

The three-step pipeline

engine/crates/rocky-cli/src/output.rs       (Rust source of truth)
        │
        ▼  cargo run -- export-schemas schemas/
schemas/*.schema.json                        (committed)
        │
        ├──▶  sdk/python/src/rocky_sdk/types_generated/   (Pydantic v2)
        └──▶  editors/vscode/src/types/generated/                       (TypeScript)

Canonical workflow

From the monorepo root:

# 1. Edit the Rust struct
$EDITOR engine/crates/rocky-cli/src/output.rs

# 2. Run the full codegen pipeline
just codegen

# 3. Review the diff — you should see changes in 3 places:
git status
#   engine/crates/rocky-cli/src/output.rs        ← your edit
#   schemas/<command>.schema.json                 ← regenerated
#   sdk/python/src/rocky_sdk/types_generated/…    ← regenerated
#   editors/vscode/src/types/generated/…          ← regenerated

# 4. Commit all of it in ONE commit
git add engine/ schemas/ sdk/ integrations/ editors/
git commit -m "feat(engine): add <field> to <command>Output"

Never commit a Rust output change without the regenerated bindings. The codegen-drift CI workflow (.github/workflows/codegen-drift.yml) runs just codegen and fails if git diff is non-empty.

What just codegen actually does

Three recipes in justfile, runnable individually:

Both codegen-sdk and codegen-vscode intentionally overwrite the output directory and then git checkout HEAD -- <barrel> to restore the curated re-export files. Do not hand-edit files under types_generated/ or types/generated/ other than those two barrels — the next codegen run nukes them.

Adding a new CLI command schema

1. Add (or edit) the typed struct in engine/crates/rocky-cli/src/output.rs (or commands/<name>.rs) deriving JsonSchema:

   #[derive(Debug, Serialize, Deserialize, JsonSchema)]
   pub struct MyCommandOutput { ... }

2. Register it in engine/crates/rocky-cli/src/commands/export_schemas.rs::schemas().
3. Run just codegen.
4. For the dagster consumer: re-export the new type from integrations/dagster/src/dagster_rocky/types.py (in the re-export section near the bottom), then add a dispatch entry in parse_rocky_output(), add a RockyResource method in resource.py, and a fixture + test (see integrations/dagster/AGENTS.md for the 9-step checklist).
5. For the vscode consumer: no extra wiring — src/types/rockyJson.ts is already a 100% type-alias shim over src/types/generated/index.ts.

Fixture drift (related but distinct)

scripts/regen_fixtures.sh (aka just regen-fixtures) captures live rocky --output json output against the playground POCs into integrations/dagster/tests/fixtures_generated/. This is a drift-detection corpus — test_generated_fixtures.py re-validates the captured JSON against the current Pydantic models. The dagster parsing tests themselves load hand-crafted Python dicts from integrations/dagster/tests/scenarios.py, exposed as *_json pytest fixtures via conftest.py.

When to regen fixtures:

• After a schema change that affects the shape of an output (new fields, renamed fields, changed types).
• Before committing, run just regen-fixtures and check that test_generated_fixtures.py still passes. If it doesn't, the captured shape no longer matches the Pydantic models — usually means the codegen step was skipped.

Prerequisite: the release binary at engine/target/release/rocky must exist (just codegen already builds it).