feat: Add WithReverseEdge() option for history-to-entity traversal

[frisbm]

@ -0,0 +1,85 @@

Description

Closes #81

Implements enthistory.WithReverseEdge() option that generates reverse edges from history schemas back to their original entities. When enabled, history schemas include an edge that allows traversal back to the original entity.

Changes:

• Added ReverseEdge bool field to HistoryOptions struct in generate.go
• Added WithReverseEdge() option function in generate.go
• Added historyEdge struct implementing ent.Edge interface
• Added reverseEdge() helper to build edge descriptors
• Added ReverseEdge bool field to Config struct in extension.go
• Added WithReverseEdgeExtension() option function in extension.go
• Updated historyFromMutation.tmpl to populate edge FK when reverse edge is enabled
• Updated internal/schemast/edge.go to support Immutable flag in edge AST generation

Generated schema output example:

func (CharacterHistory) Edges() []ent.Edge {
    return []ent.Edge{
        edge.To("character", Character.Type).
            Unique(),
    }
}

Motivation and Context

This enables idiomatic ent traversal from history records back to their original entities:

• historyRecord.QueryCharacter() - traverse from history to original
• client.CharacterHistory.Query().WithCharacter().All(ctx) - eager load original entities

Previously, users had to manually query the original entity using the ref field. This feature provides first-class edge support for cleaner, more idiomatic code.

How Has This Been Tested?

Added 3 integration tests in _examples/enthistory_basic_test.go:

1. "Can traverse from history to original entity using reverse edge" - Verifies QueryCharacter() returns the correct original entity
2. "Can query history with character edge using WithCharacter" - Verifies eager loading with WithCharacter() works correctly
3. "Reverse edge returns not found for deleted entities" - Verifies edge returns NotFound when original entity is deleted

All 22 tests pass including the original test suite (delete tracking works correctly).

cd _examples && go test ./. -v

Screenshots (if appropriate):

N/A

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation (update or addition to documentation for this project)

Checklist:

• My code follows the code style of this project.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.

Usage

// In entc.go - two options must be enabled:

// 1. Generate schema with edge
enthistory.Generate("./schema", []ent.Interface{
    &schema.Character{},
},
    enthistory.WithReverseEdge(),
)

// 2. Extension populates edge FK when creating history
entc.Generate("./schema", ...,
    entc.Extensions(
        enthistory.NewHistoryExtension(
            enthistory.WithReverseEdgeExtension(),
        ),
    ),
)

[flume-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[frisbm]

@lillialjackson @josue @corvramirez
After this one, pull main locally and run make tag and then go back to https://github.com/flume/enthistory/releases and cut a new release based on the tag