Address #227 and #262

Addressed a bottlenecking issue in the doctor causing a freeze and skipping broken specs in a report when using a timeline.

Author: daveshanley

AGENTS.md

@@ -65,6 +65,8 @@ All `cmd/` implementation files use their canonical names (e.g., `cmd/summary.go
 - `report` should emit semantic `path` values whenever possible.
 - If semantic normalization rewrites an engine path, preserve the original path in `rawPath`.
 - Parameter identity must not depend on array index positions when a stable semantic name exists.
+- Historical `report` output must surface partial-success state in `metaData` instead of relying on stderr warnings alone.
+- `metaData.skippedCommits` is the machine-readable list of git/GitHub history revisions that were skipped because they failed to normalize or render.
 
 ### Left/right behavior
 
@@ -76,6 +78,7 @@ All `cmd/` implementation files use their canonical names (e.g., `cmd/summary.go
 
 - Mixed-success histories should limp on with warnings when at least one comparable commit renders successfully.
 - `summary`, `markdown-report`, and `html-report` should fail only when every candidate commit fails to render/build.
+- Historical `report` output should limp on when at least one history item renders, and must set `metaData.partial = true` when any commits were skipped.
 - “No prior comparable version” and “no changes found” are distinct states.
 
 ### HTML payload integrity

cmd/console_test.go

@@ -94,9 +94,11 @@ func TestWrapConsoleStartError(t *testing.T) {
 func TestConsoleCommand_NoPriorVersionText(t *testing.T) {
 	originalExtract := extractHistoryFromFile
 	originalPopulate := populateHistory
+	originalPopulateDetailed := populateHistoryDetailed
 	t.Cleanup(func() {
 		extractHistoryFromFile = originalExtract
 		populateHistory = originalPopulate
+		populateHistoryDetailed = originalPopulateDetailed
 	})
 
 	extractHistoryFromFile = func(repoDirectory, filePath string,
@@ -110,6 +112,12 @@ func TestConsoleCommand_NoPriorVersionText(t *testing.T) {
 	) ([]*model.Commit, []error) {
 		return []*model.Commit{}, nil
 	}
+	populateHistoryDetailed = func(commitHistory []*model.Commit,
+		progressChan chan *model.ProgressUpdate, errorChan chan model.ProgressError, opts git.HistoryOptions,
+		breakingConfig *whatChangedModel.BreakingRulesConfig,
+	) (*git.HistoryBuildResult, []error) {
+		return &git.HistoryBuildResult{}, nil
+	}
 
 	cmd := testRootCmd(GetConsoleCommand(), "--no-logo", "--no-color", "..", "sample-specs/petstorev3.json")
 	output := captureStdout(t, func() {

cmd/engine.go

@@ -4,15 +4,18 @@
 package cmd
 
 import (
+	"bytes"
 	"fmt"
 	"os"
+	"strings"
 
 	"github.com/pb33f/doctor/changerator"
 	drModel "github.com/pb33f/doctor/model"
 	v3 "github.com/pb33f/doctor/model/high/v3"
 	whatChangedModel "github.com/pb33f/libopenapi/what-changed/model"
 	"github.com/pb33f/openapi-changes/internal/breakingrules"
 	"github.com/pb33f/openapi-changes/model"
+	"go.yaml.in/yaml/v4"
 )
 
 // changeratorResult owns the doctor-side resources created for a single comparison.
@@ -51,6 +54,9 @@ func runChangerator(commit *model.Commit, breakingConfig *whatChangedModel.Break
 	if err != nil {
 		return nil, modelBuildError("original", commitSourceLabel(commit, false), err)
 	}
+	if isSelfContainedIdenticalComparison(commit) {
+		return nil, nil
+	}
 
 	rightDrDoc := drModel.NewDrDocumentAndGraph(rightModel)
 	leftDrDoc := drModel.NewDrDocumentAndGraph(leftModel)
@@ -92,6 +98,54 @@ func runChangerator(commit *model.Commit, breakingConfig *whatChangedModel.Break
 	}, nil
 }
 
+func isSelfContainedIdenticalComparison(commit *model.Commit) bool {
+	if commit == nil || !commit.Synthetic || len(commit.Data) == 0 || len(commit.OldData) == 0 {
+		return false
+	}
+	if !bytes.Equal(commit.Data, commit.OldData) {
+		return false
+	}
+	return !rootBytesContainExternalRefs(commit.OldData) && !rootBytesContainExternalRefs(commit.Data)
+}
+
+func rootBytesContainExternalRefs(spec []byte) bool {
+	if len(spec) == 0 {
+		return false
+	}
+	var root yaml.Node
+	if err := yaml.Unmarshal(spec, &root); err != nil {
+		return true
+	}
+	return nodeContainsExternalRef(&root)
+}
+
+func nodeContainsExternalRef(node *yaml.Node) bool {
+	if node == nil {
+		return false
+	}
+	if node.Kind == yaml.MappingNode {
+		for i := 0; i+1 < len(node.Content); i += 2 {
+			key := node.Content[i]
+			value := node.Content[i+1]
+			if key != nil && key.Value == "$ref" && value != nil && value.Kind == yaml.ScalarNode {
+				if value.Value != "" && !strings.HasPrefix(value.Value, "#") {
+					return true
+				}
+			}
+			if nodeContainsExternalRef(value) {
+				return true
+			}
+		}
+		return false
+	}
+	for _, child := range node.Content {
+		if nodeContainsExternalRef(child) {
+			return true
+		}
+	}
+	return false
+}
+
 func rewriteOutputLocations(ctr *changerator.Changerator, docChanges *whatChangedModel.DocumentChanges, rewriters []model.DocumentPathRewriter) {
 	if len(rewriters) == 0 {
 		return

cmd/loaders.go

@@ -19,10 +19,17 @@ import (
 )
 
 var processGithubRepo = git.ProcessGithubRepo
+var processGithubRepoDetailed = git.ProcessGithubRepoDetailed
 var extractHistoryFromFile = git.ExtractHistoryFromFile
 var populateHistory = git.PopulateHistory
+var populateHistoryDetailed = git.PopulateHistoryDetailed
 var httpGet = http.Get
 
+type loadedHistoryResult struct {
+	Commits        []*model.Commit
+	SkippedCommits []string
+}
+
 // progressDrainer drains git progress channels that use synchronous sends.
 // Call close() before reading collected warnings or errors.
 type progressDrainer struct {
@@ -116,7 +123,7 @@ func (d *progressDrainer) collectErrors(errs []error) error {
 	return errors.Join(all...)
 }
 
-func loadGitHubCommits(rawURL string, opts summaryOpts, breakingConfig *whatChangedModel.BreakingRulesConfig) ([]*model.Commit, error) {
+func loadGitHubCommitsDetailed(rawURL string, opts summaryOpts, breakingConfig *whatChangedModel.BreakingRulesConfig) (*loadedHistoryResult, error) {
 	specURL, err := url.Parse(rawURL)
 	if err != nil {
 		return nil, fmt.Errorf("invalid URL: %w", err)
@@ -127,7 +134,7 @@ func loadGitHubCommits(rawURL string, opts summaryOpts, breakingConfig *whatChan
 	}
 
 	d := makeProgressDrainer()
-	commits, errs := processGithubRepo(user, repo, filePath,
+	result, errs := processGithubRepoDetailed(user, repo, filePath,
 		d.ProgressChan, d.ErrorChan, git.HistoryOptions{
 			BaseCommit:     opts.baseCommit,
 			Limit:          opts.limit,
@@ -141,13 +148,28 @@ func loadGitHubCommits(rawURL string, opts summaryOpts, breakingConfig *whatChan
 		return nil, err
 	}
 
+	if result == nil {
+		return nil, nil
+	}
+	commits := result.Commits
 	if opts.latest && len(commits) > 1 {
 		commits = commits[:1]
 	}
-	return commits, nil
+	return &loadedHistoryResult{
+		Commits:        commits,
+		SkippedCommits: result.SkippedCommits,
+	}, nil
 }
 
-func loadGitHistoryCommits(gitPath, filePath string, opts summaryOpts, breakingConfig *whatChangedModel.BreakingRulesConfig) ([]*model.Commit, error) {
+func loadGitHubCommits(rawURL string, opts summaryOpts, breakingConfig *whatChangedModel.BreakingRulesConfig) ([]*model.Commit, error) {
+	result, err := loadGitHubCommitsDetailed(rawURL, opts, breakingConfig)
+	if result == nil {
+		return nil, err
+	}
+	return result.Commits, err
+}
+
+func loadGitHistoryCommitsDetailed(gitPath, filePath string, opts summaryOpts, breakingConfig *whatChangedModel.BreakingRulesConfig) (*loadedHistoryResult, error) {
 	if gitPath == "" || filePath == "" {
 		return nil, errors.New("please supply a path to a git repo and a path to a file")
 	}
@@ -178,7 +200,7 @@ func loadGitHistoryCommits(gitPath, filePath string, opts summaryOpts, breakingC
 	}
 
 	populateDrainer := makeProgressDrainer()
-	commits, errs = populateHistory(commits,
+	result, errs := populateHistoryDetailed(commits,
 		populateDrainer.ProgressChan, populateDrainer.ErrorChan, git.HistoryOptions{
 			LimitTime:      opts.limitTime,
 			Base:           opts.base,
@@ -190,13 +212,31 @@ func loadGitHistoryCommits(gitPath, filePath string, opts summaryOpts, breakingC
 		return nil, err
 	}
 
-	if len(commits) == 0 {
+	if result == nil {
 		return nil, nil
 	}
+	commits = result.Commits
+	if len(commits) == 0 {
+		return &loadedHistoryResult{SkippedCommits: result.SkippedCommits}, nil
+	}
 	if opts.latest {
 		commits = commits[:1]
 	}
-	return commits, nil
+	return &loadedHistoryResult{
+		Commits:        commits,
+		SkippedCommits: result.SkippedCommits,
+	}, nil
+}
+
+func loadGitHistoryCommits(gitPath, filePath string, opts summaryOpts, breakingConfig *whatChangedModel.BreakingRulesConfig) ([]*model.Commit, error) {
+	result, err := loadGitHistoryCommitsDetailed(gitPath, filePath, opts, breakingConfig)
+	if result == nil {
+		return nil, err
+	}
+	if len(result.Commits) == 0 {
+		return nil, nil
+	}
+	return result.Commits, err
 }
 
 func loadLeftRightCommits(left, right string, opts summaryOpts) ([]*model.Commit, error) {