Feature Proposal: Add `calm evolve` with dry-run support for tactical schema migrations

Open LeighFinegold opened this issue 5 months ago • 1 comments

1. Overview

Introduce a new calm evolve subcommand that:

Requires only a --to schema version (the source version is detected automatically).
Supports migrating any directory of CALM documents via a generic --dir flag.
Supports Calm‑Hub repositories and via a --hub flag (or via the mechanism which we plan to link the cli to calm-hub)
Provides a --dry-run mode to preview changes without modifying files or pushing commits.

Schema drift between version bumps and our published artifacts (patterns, examples, docs, Calm‑Hub stores) is time‑consuming to manage manually. This even impacts calm repo developers maintaining and upgrading tests to support schema versions.
Bundling every historic schema leads to unbounded CLI growth and maintenance burden.
Users need a consistent, automated way to upgrade CALM documents wherever they live.

calm evolve \
  --to <newVersion> \
  [--dir <path>] \
  [--hub <repository-url-or-id>] \
  [--dry-run]

Flag	Description
`--to` (required)	Target CALM schema version to migrate toward.
`--dir`	Directory containing CALM documents to migrate (defaults to current working directory).
`--hub`	Calm‑Hub repository URL or identifier; when present, the tool clones/pulls, migrates, and pushes.
`--dry-run`	Output intended changes as unified diffs; do not modify files or push commits.

Discovery
- Scan all YAML/JSON files under --dir or in the Calm‑Hub repo for their calmSchemaVersion.
Schema Fetch & Cache
- For each unique source version and the specified target, download schemas on demand via calmhub or leverage the bundled schemas via the cli
Migration
- Apply the appropriate transform script for each source→target pair.
- In --dry-run mode: emit unified diffs to stdout (or to a report file).
- In apply mode: overwrite files in place (backing up originals) or commit changes to the Calm‑Hub repository.
Reporting
- Summarize the number of files processed, migrated, skipped (already up‑to‑date), and any errors that require manual intervention.

Scenario	Example Invocation
Migrate local documents to v2.0.0	`calm evolve --to 2.0.0 --dir ./my-docs`
Preview migrations without changes	`calm evolve --to 2.0.0 --dry-run`
Migrate a Calm‑Hub repo	`calm evolve --to 2.0.0 --hub calmhub.example.org`
CI check across examples or docs repos	`calm evolve --to ${LATEST} --dir . --dry-run`

Automatic Source Detection: No manual --from version entry and no pre‑bundled archive of historic schemas.
Unified Tooling: One command handles both directory‑based and remote Calm‑Hub document sets.
Safety via Dry‑Run: Users and CI can validate intended migrations before applying.
Controlled Footprint: Only the migration scripts and runtime fetch logic ship with the CLI.
AI-driven Assistance: Integrates with MCP server AI tooling to provide automated migration suggestions and validation checks.

Part of that discussion would be agreeing on how schemas would be fetched (e.g. dynamic remote fetching) and what schemas would be supported. See comment https://github.com/finos/architecture-as-code/issues/1423#issuecomment-3082614061

Jul 17 '25 05:07 LeighFinegold

As discussed, next steps would be to provide a working PoC for this feature.

I think the two realistic options are:

add a deterministic solution based on transformers of some sort . . . this may result in a lot of support queries as we hit inevitable edge cases as architectures and patterns can be extremely complex.
add a feature including version specific prompts to calm-mcp . . . this is likely to be non-deterministic but with appropriate prompting may be able to iterate to a solution.

Question

If we added this feature would we expect to make it a mandatory requirement for schema changes before they could be released?

Sounds like a great feature, but may be very time consuming to support.

Jul 17 '25 15:07 rocketstack-matt