Implements a clean and correct implementation for #85

full commit comparison is now available. Uses the rolodex and a custom revision file system to handle this correctly.

Author: daveshanley

AGENTS.md

@@ -12,7 +12,7 @@ Public documentation:
 
 `openapi-changes` is a Go CLI for comparing OpenAPI specifications across:
 
-- direct left/right file or URL comparison
+- direct left/right file, URL, or git-revision comparison
 - local git history for a file in a repository
 - GitHub-hosted file history via file URL
 
@@ -65,6 +65,7 @@ All `cmd/` implementation files use their canonical names (e.g., `cmd/summary.go
 
 - Left/right comparisons are synthetic comparisons, not fake git history.
 - Do not emit synthetic commit metadata in left/right machine- or human-facing report output.
+- Git revision inputs (`revision:path`) resolve `$ref` siblings from the same revision via `GitRevisionFS`, not from the working tree.
 
 ### Failure semantics
 
@@ -99,7 +100,9 @@ All `cmd/` implementation files use their canonical names (e.g., `cmd/summary.go
 - `cmd/console.go` — launches the interactive Bubbletea terminal UI
 - `cmd/flatten_report.go` — flattens hierarchical change reports into flat structures with hashed changes and normalized paths
 - `cmd/report_common.go` — shared utilities: summary report creation from commits, formatted report file writing
+- `cmd/left_right_sources.go` — resolves local, URL, and git-revision inputs into uniform comparison sources with proper document configuration
 - `git/read_local.go` — local git history extraction via git commands; commit and file content preparation
+- `git/revision_fs.go` — virtual filesystem that reads files from a git revision for `$ref` resolution in revision-scoped comparisons
 - `git/github.go` — remote file history fetching from GitHub repos via doctor GitHub service
 - `html-report/generator.go` — renders self-contained HTML using embedded templates and syntax-highlighted code
 - `model/report.go` — hashed change structures with SHA256 hashes and raw paths for serialization

README.md

@@ -9,8 +9,8 @@
 
 ## The world's **_most powerful and complete_** OpenAPI diff tool.
 
-`openapi-changes` lets you inspect what changed in an OpenAPI specification between two files, 
-across local git history, or directly from a GitHub-hosted file URL.
+`openapi-changes` lets you inspect what changed in an OpenAPI specification between two files,
+between git revisions of the same file, across local git history, or directly from a GitHub-hosted file URL.
 
 It can render the same semantic change model as:
 
@@ -128,6 +128,21 @@ A self-contained, offline HTML report with interactive timeline, change explorer
 
 ---
 
+## Comparing git revisions
+
+Compare a file at different git revisions without checking out branches:
+
+```bash
+openapi-changes summary HEAD~1:openapi.yaml ./openapi.yaml
+openapi-changes html-report main:api/openapi.yaml feature-branch:api/openapi.yaml
+```
+
+The `revision:path` syntax works with any git ref -- branches, tags, `HEAD~N`, commit SHAs.
+The path is relative to the repository root. This works with all commands and supports
+multi-file specs with `$ref` references resolved from the same revision.
+
+---
+
 ## Documentation
 
 ### [Quick Start Guide 🚀](https://pb33f.io/openapi-changes/quickstart/)

cmd/common.go

@@ -8,7 +8,6 @@ import (
 	"image/color"
 	"net/url"
 	"os"
-	"strings"
 
 	"charm.land/lipgloss/v2"
 	"github.com/pb33f/doctor/terminal"
@@ -209,9 +208,14 @@ func loadCommitsFromArgs(args []string, opts summaryOpts, breakingConfig *whatCh
 	if len(args) == 1 {
 		return loadGitHubCommits(args[0], opts, breakingConfig)
 	}
-	firstURL, _ := url.Parse(args[0])
-	if firstURL != nil && strings.HasPrefix(firstURL.Scheme, "http") {
-		return loadLeftRightCommits(args[0], args[1], opts, breakingConfig)
+	if isHTTPURL(args[0]) {
+		return loadLeftRightCommits(args[0], args[1], opts)
+	}
+	if _, _, ok := parseGitRef(args[0]); ok {
+		return loadLeftRightCommits(args[0], args[1], opts)
+	}
+	if _, _, ok := parseGitRef(args[1]); ok {
+		return loadLeftRightCommits(args[0], args[1], opts)
 	}
 	f, statErr := os.Stat(args[0])
 	if statErr != nil {
@@ -220,7 +224,7 @@ func loadCommitsFromArgs(args []string, opts summaryOpts, breakingConfig *whatCh
 	if f.IsDir() {
 		return loadGitHistoryCommits(args[0], args[1], opts, breakingConfig)
 	}
-	return loadLeftRightCommits(args[0], args[1], opts, breakingConfig)
+	return loadLeftRightCommits(args[0], args[1], opts)
 }
 
 // printCommandUsage prints lipgloss-styled usage for any doctor-based command.
@@ -239,6 +243,7 @@ func printCommandUsage(commandName, description string, palette terminal.Palette
 	fmt.Println()
 	fmt.Println("Examples:")
 	fmt.Printf("  %s\n", cmdStyle.Render("openapi-changes "+commandName+" ./specs/old.yaml ./specs/new.yaml"))
+	fmt.Printf("  %s\n", cmdStyle.Render("openapi-changes "+commandName+" HEAD~1:openapi.yaml ./openapi.yaml"))
 	fmt.Printf("  %s\n", cmdStyle.Render("openapi-changes "+commandName+" https://github.com/user/repo/blob/main/openapi.yaml"))
 	fmt.Printf("  %s\n", cmdStyle.Render("openapi-changes "+commandName+" /path/to/git/repo path/to/openapi.yaml"))
 	fmt.Println()

cmd/console.go

@@ -60,7 +60,7 @@ func GetConsoleCommand() *cobra.Command {
 		Use:          "console",
 		Short:        "Interactive terminal UI for exploring changes",
 		Long:         "Navigate through changes visually in an interactive terminal UI built with Bubbletea, using the doctor changerator engine.",
-		Example:      "openapi-changes console /path/to/git/repo path/to/file/in/repo/openapi.yaml",
+		Example:      "openapi-changes console HEAD~1:openapi.yaml ./openapi.yaml",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			input, err := prepareCommandRun(cmd, args, printConsoleUsage)
 			if err != nil {

cmd/html_report.go

@@ -9,7 +9,6 @@ import (
 	"errors"
 	"fmt"
 	"os"
-	"path/filepath"
 	"strconv"
 	"text/template"
 	"time"
@@ -94,10 +93,11 @@ func generateHTMLReport(commits []*model.Commit, breakingConfig *whatChangedMode
 		History:       history,
 	}
 
-	// For left/right comparisons, include sanitized spec paths (basename only)
+	// For left/right comparisons, preserve explicit git-ref and URL labels while
+	// keeping plain local files compact.
 	if len(args) == 2 && len(items) == 1 {
-		payload.OriginalPath = filepath.Base(args[0])
-		payload.ModifiedPath = filepath.Base(args[1])
+		payload.OriginalPath = displayLabelForHTML(args[0])
+		payload.ModifiedPath = displayLabelForHTML(args[1])
 	}
 
 	// json.Marshal escapes <, >, & by default — prevents </script> injection.
@@ -135,7 +135,7 @@ func GetHTMLReportCommand() *cobra.Command {
 		Use:          "html-report",
 		Short:        "Generate an interactive HTML report",
 		Long:         "Generate a rich, interactive HTML report. The report is fully self-contained and works offline.",
-		Example:      "openapi-changes html-report /path/to/git/repo path/to/file/in/repo/openapi.yaml",
+		Example:      "openapi-changes html-report HEAD~1:openapi.yaml ./openapi.yaml",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			input, err := prepareCommandRun(cmd, args, printHTMLReportUsage)
 			if err != nil {

cmd/html_report_test.go

@@ -5,6 +5,8 @@ package cmd
 
 import (
 	"encoding/json"
+	"net/http"
+	"net/http/httptest"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -20,7 +22,6 @@ func TestGenerateHTMLReport_UnchangedLeftRight(t *testing.T) {
 		"../sample-specs/petstorev3.json",
 		"../sample-specs/petstorev3.json",
 		summaryOpts{noColor: true},
-		nil,
 	)
 	require.NoError(t, err)
 
@@ -37,7 +38,6 @@ func TestGenerateHTMLReport_LeftRightIncludesSanitizedPaths(t *testing.T) {
 		"../sample-specs/petstorev3-original.json",
 		"../sample-specs/petstorev3.json",
 		summaryOpts{noColor: true},
-		nil,
 	)
 	require.NoError(t, err)
 
@@ -54,6 +54,54 @@ func TestGenerateHTMLReport_LeftRightIncludesSanitizedPaths(t *testing.T) {
 	assert.Contains(t, content, "<!DOCTYPE html")
 }
 
+func TestGenerateHTMLReport_LeftRightPreservesGitRefPaths(t *testing.T) {
+	repoDir := createGitSpecRepo(t)
+	chdirForTest(t, repoDir)
+
+	commits, err := loadLeftRightCommits(
+		"HEAD~1:openapi.yaml",
+		"HEAD:openapi.yaml",
+		summaryOpts{noColor: true},
+	)
+	require.NoError(t, err)
+
+	report, err := generateHTMLReport(commits, nil, true,
+		"HEAD~1:openapi.yaml",
+		"HEAD:openapi.yaml",
+	)
+	require.NoError(t, err)
+	require.NotNil(t, report)
+
+	content := string(report)
+	assert.Contains(t, content, `"originalPath":"HEAD~1:openapi.yaml"`)
+	assert.Contains(t, content, `"modifiedPath":"HEAD:openapi.yaml"`)
+}
+
+func TestGenerateHTMLReport_LeftRightPreservesURLPaths(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path == "/left.yaml" {
+			_, _ = w.Write([]byte("openapi: 3.0.3\ninfo:\n  title: Left\n  version: '1.0'\npaths: {}\n"))
+			return
+		}
+		_, _ = w.Write([]byte("openapi: 3.0.3\ninfo:\n  title: Right\n  version: '1.1'\npaths:\n  /pets:\n    get:\n      responses:\n        \"200\":\n          description: ok\n"))
+	}))
+	defer server.Close()
+
+	leftURL := server.URL + "/left.yaml"
+	rightURL := server.URL + "/right.yaml"
+
+	commits, err := loadLeftRightCommits(leftURL, rightURL, summaryOpts{noColor: true})
+	require.NoError(t, err)
+
+	report, err := generateHTMLReport(commits, nil, true, leftURL, rightURL)
+	require.NoError(t, err)
+	require.NotNil(t, report)
+
+	content := string(report)
+	assert.Contains(t, content, `"originalPath":"`+leftURL+`"`)
+	assert.Contains(t, content, `"modifiedPath":"`+rightURL+`"`)
+}
+
 func TestBuildHTMLReportItems_AllCommitsFail(t *testing.T) {
 	items, err := buildHTMLReportItems([]*model.Commit{makeSwagger2Commit(t)}, nil)
 	require.Error(t, err)
@@ -66,7 +114,6 @@ func TestBuildHTMLReportItems_PartialFailureReturnsPartialResults(t *testing.T)
 		"../sample-specs/petstorev3-original.json",
 		"../sample-specs/petstorev3.json",
 		summaryOpts{noColor: true},
-		nil,
 	)
 	require.NoError(t, err)
 	require.NotEmpty(t, commits)
@@ -88,7 +135,6 @@ func TestGenerateHTMLReport_PartialFailureReturnsPartialReport(t *testing.T) {
 		"../sample-specs/petstorev3-original.json",
 		"../sample-specs/petstorev3.json",
 		summaryOpts{noColor: true},
-		nil,
 	)
 	require.NoError(t, err)
 	require.NotEmpty(t, commits)
@@ -136,7 +182,6 @@ func TestBuildHTMLReportItems_PreservesSchemaNodesInDocumentTree(t *testing.T) {
 		"../sample-specs/petstorev3-original.json",
 		"../sample-specs/petstorev3.json",
 		summaryOpts{noColor: true},
-		nil,
 	)
 	require.NoError(t, err)
 	require.NotEmpty(t, commits)
@@ -179,7 +224,6 @@ func TestBuildHTMLReportItems_SplitsStandardAndChangeExplorerGraphs(t *testing.T
 		"../sample-specs/petstorev3-original.json",
 		"../sample-specs/petstorev3.json",
 		summaryOpts{noColor: true},
-		nil,
 	)
 	require.NoError(t, err)
 	require.NotEmpty(t, commits)