Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,29 @@ Both DSLs live inside `crates/hm-dsl-engine/` so they ship with the crate:

- `crates/hm-dsl-engine/harmont-py/` — the `harmont` Python package (pipeline DSL).
- `crates/hm-dsl-engine/harmont-ts/` — the `harmont` TypeScript package (pipeline DSL).

## Keep the SDK, `hm init` templates, and docs in sync

The toolchain helpers in `crates/hm-dsl-engine/` (e.g.
`harmont-py/harmont/_rust.py`, `harmont-ts/src/toolchains/rust.ts`) are the
**public authoring SDK**. They have two downstream surfaces that drift silently
unless you update them in the same change. **A toolchain change is not done until
all three agree:**

1. **`hm init` templates** — `crates/hm/src/commands/init_templates/<lang>.py`,
embedded into the binary via `include_str!` in `crates/hm/src/commands/init.rs`.
When you change a toolchain's recommended entrypoint (e.g. Rust →
`rust.project().ci()`), update the matching template so scaffolded projects use
the current API. Roundtrip tests: `crates/hm/tests/cmd_init.rs`.

2. **Pipeline-SDK reference docs** —
`docs-site/content/docs/pipeline-sdk/reference/toolchains/<lang>.mdx` are
**auto-generated from the Python docstrings** in `harmont-py` (griffe →
`docs-site/scripts/extract-dsl-api.py` → `generate-dsl-docs.ts`); they carry a
"do not edit" header. So: (a) write/refresh the docstring on any method you add
or change, then (b) regenerate from the simci repo root with `make docs-generate`
(DSL-only: rebuild `docs-site/dsl-api.json` from `harmont-py`, then
`cd docs-site && npx tsx scripts/generate-dsl-docs.ts && npx tsx scripts/check-dsl-pages.ts`),
and (c) commit the regenerated `*.mdx` in the **simci (parent) repo** alongside
the gitlink bump. `check-dsl-pages.ts` guards that the committed pages match the
docstrings.
Loading
Loading