feat(schema)!: collapse doctor/why/list versioning to a single v1

[kjanat]

Closes #80.

Not enough external adoption yet to justify carrying v1/v2/v3 compat
simultaneously across doctor/why/list. Purges the old versions,
treats today's shape as the sole, first version.

Breaking

• --schema-version now only accepts 1 (was 1..=3).
• doctor --json / why --json always emit the structured report that
  used to require --schema-version 3; the flat v1/v2 shape is gone
  from both output paths.

Changes

• src/schema/v1.rs/v2.rs/v3.rs deleted; source-label dispatch
  collapses to labels::flat_source_label/structured_source_label
  (list vs doctor/why), no version parameter anywhere.
• CURRENT_VERSION/DOCTOR_CURRENT_VERSION/WHY_CURRENT_VERSION
  collapse to a single schema::SCHEMA_VERSION = 1.
• src/schema/doctor_v3.rs -> src/schema/doctor.rs; V3-suffixed
  structs across doctor.rs/why.rs drop the suffix.
• 10 superseded schemas/*.json deleted; the 3 kept files drop their
  version suffix (doctor.v3.schema.json -> doctor.schema.json, etc).

Test plan

• cargo test --all-features (879 unit + all integration suites green)
• cargo clippy --all-targets --all-features -- -D warnings -D clippy::all clean
• cargo fmt --check clean
• cargo run --features schema -- schema --all --output schemas is a no-op against the committed files (drift guard)

[coderabbitai]

📝 Walkthrough

Collapse doctor, why, and list JSON-schema versioning to a single contract (schema_version = 1), removing all legacy v1/v2/v3 support.

• Restrict --schema-version to 1 only (reject 2/3) and update CLI/help/docs accordingly.
• Make doctor --json and why --json always emit the structured (non-legacy flat) report shape.
• Delete versioned schema modules and types (src/schema/v1.rs, v2.rs, v3.rs, plus v3 doctor schema types) and simplify schema routing/constants to schema::SCHEMA_VERSION = 1.
• Rename/collapse current doctor schema types (doctor_v3.rs → doctor.rs, drop V3 suffixes across relevant structs/enums).
• Regenerate and commit versionless schema/example artefacts:
  • schemas/doctor.schema.json, schemas/why.schema.json, schemas/list.schema.json (+ updated *.example.json)
  • Update $id, $defs, $ref targets, titles/descriptions, and schema_version consts
  • Remove superseded schemas/*v{1,2,3}* files and examples.
• Remove schema-version plumbing from doctor, why, list, and info; update label handling to use flat_source_label vs structured_source_label, and update fqn to no longer take schema-version input.
• Simplify schema generation (runner schema) to commit only versionless schemas; patch in command-derived TaskSourceLabel/provider labelling and adjust compat (e.g., doctor schema Overrides.quiet requirement handling).
• Improve runner config init scaffolding:
  • Generate initial runner.init.toml from RunnerConfig’s schemars metadata with drift-guard coverage.
  • Load RunnerConfig’s INIT_TEMPLATE via include_str!("../schemas/runner.init.toml").
  • Add drift-detection/error handling to avoid raw panics on template drift (and ensure runner schema --all reports clean CLI errors).

Breaking: legacy flat JSON output shapes and versioned v1/v2/v3 schema URLs/filenames are no longer supported.

Validated with cargo test --all-features, cargo clippy, cargo fmt --check, and a schema-generation drift check.

Walkthrough

This PR collapses the doctor, why, and list JSON schema split into a single schema_version = 1 contract. Shared schema helpers now use one constant, the CLI flag is pinned to 1, command dispatch stops threading schema versions through JSON-aware commands, and the doctor/why payloads are rewritten to unified structured shapes. Schema generation now emits versionless committed schema files, updates the scaffold template source, and removes the superseded versioned artefacts.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI as src/cli.rs
  participant Lib as src/lib.rs
  participant Cmd as src/cmd/doctor.rs
  participant Schema as src/schema/doctor.rs
  CLI->>Lib: --schema-version 1
  Lib->>Cmd: doctor(ctx, overrides, json)
  Cmd->>Schema: DoctorReport::build(...)
  Cmd->>Cmd: serde_json::to_string_pretty(...)

Loading

sequenceDiagram
  participant CmdSchema as src/cmd/schema.rs
  participant Config as src/config.rs
  participant Schemas as schemas/*.json
  participant Template as schemas/runner.init.toml
  CmdSchema->>Config: include_str!("../schemas/runner.init.toml")
  CmdSchema->>Template: render_init_template()
  CmdSchema->>Schemas: write committed artefacts

Loading

Possibly related PRs

• kjanat/runner#22: Touches the same JSON command entry points and schema-aware command plumbing that this PR reshapes.
• kjanat/runner#50: Covers the schema-generation pipeline that this PR rewires for versionless committed schemas.
• kjanat/runner#51: Introduces the versioned doctor/why schema machinery that this PR removes.

Suggested labels: enhancement, documentation, breaking-change

Poem

Arrr, the version ghosts are walked off the plank,
and one clean schema now holds rank.
No more v2 squabbling in the mist —
just tidy JSON, sharp and bliss.
SCHEMA_VERSION = 1, matey ☠️

🚥 Pre-merge checks | ✅ 6 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR also adds unrelated config, tooling, and init-template work beyond collapsing doctor/why/list versioning.	Split the config/init-template, resolver-label, and editor/Cargo changes into separate PRs unless they are required by #80.
Semver Version Bump Validation	⚠️ Warning	Cargo.toml stayed at 0.18.1 in base and PR, and site/package.json stayed at 0.0.0; this PR breaks CLI/schema contracts and drops public symbols, so the required MAJOR bump is missing.	Bump the published version in Cargo.toml (and any other release manifest) to a new MAJOR SemVer release, e.g. 1.0.0, then re-run the checks.

✅ Passed checks (6 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly describes the main breaking change: collapsing schema versioning to a single v1.
Description check	✅ Passed	The description matches the schema-version collapse and removal of older JSON shapes.
Linked Issues check	✅ Passed	The changes satisfy #80 by pinning --schema-version to 1, dropping versioned schema files, and removing V3 suffixes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Changelog Update	✅ Passed	Source files changed, and CHANGELOG.md was updated under [Unreleased] with Changed/Removed/Fixed entries covering the breaking schema-version changes.
Agents.Md Documentation Updated	✅ Passed	No AGENTS.md exists anywhere in the repo, so there was nothing for this PR to update despite the architectural/CLI changes.

📋 Issue Planner

Built with CodeRabbit's Coding Plans for faster development and fewer bugs.

View plan used: #80

---

_{Comment @coderabbitai help to get the list of available commands.}