Implement Schema Diffing & Auto-Versioning

[Kinflou]

Implement Schema Diffing & Auto-Versioning

Priority

P1 (High) - Key differentiator feature

Labels

• core
• versioning
• documentation
• autodoc
• P1

Estimated Effort

2-3 weeks

Description

Implement automatic SemVer version bumping based on schema changes. This is a key differentiator for Comline - developers don't manually version their schemas.

Versioning Rules (SemVer):

• Adding new fields → minor version bump (0.1.0 → 0.2.0)
• Changing existing fields → major version bump (0.1.0 → 1.0.0)
• Documentation/comment changes → patch bump (0.1.0 → 0.1.1)

Current State

Location:

• core/src/schema/ir/diff/
• core/src/autodoc/
• core/src/package/config/ir/diff/

Framework exists but diff logic is incomplete.

TODO References

• schema/ir/diff/mod.rs:25,51
• package/config/ir/diff/versioning.rs:64
• autodoc/document.rs:37,42
• autodoc/schema.rs:24,43

Reference Documentation

See: docs/docs/knowledge/planning/ir-generation.md

Acceptance Criteria

• Diff algorithm compares FrozenUnits correctly
• SemVer bump rules implemented
• Breaking change detection works
• Changelog generation functional
• Autodoc system generates API documentation
• Integration with CAS for version history
• CLI shows version changes on build
• Documentation explains versioning rules

Tasks

• Implement FrozenUnit diff algorithm (structural comparison)
• Create SemVer bump logic based on change types
• Add breaking change detection
• Implement changelog generator (Markdown format)
• Build autodoc document generator
• Create version conflict resolver
• Add version history tracking in CAS
• Write comprehensive tests (including edge cases)
• Document versioning behavior with examples

Example Output

📊 Schema Changes Detected:
  - Added field `email` to struct `User` → MINOR bump
  - Changed type of `age` from u8 to u16 → MAJOR bump
  
Version: 0.5.2 → 1.0.0 (MAJOR change due to breaking modification)

Generated: CHANGELOG.md

Dependencies

• CLI Tool Implementation #2 CAS System (for storing version history)
• Consolidate and Complete IDL Parser #3 IR Compilation (for generating FrozenUnits)

Blocks

None (can be developed in parallel with #4 and #6)