Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions .ai-docs/bilingual-comparison.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ uses libopenapi's strict YAML/JSON parser once, checks the root version marker,
and transfers the parsed AsyncAPI tree to libasyncapi. Mixed formats, ambiguous
markers, unsupported AsyncAPI versions and partial AsyncAPI models fail clearly.

The stack uses libopenapi v0.42.0. Its default YAML alias expansion limit remains
The stack uses libopenapi v0.42.3. Its default YAML alias expansion limit remains
enabled for both formats. Excessive alias expansion fails during loading; normal
aliases retain bounded HTML previews. Doctor tests opt in to trusted excessive
aliases through libasyncapi to exercise graph bounds independently of this limit.
Expand Down Expand Up @@ -93,8 +93,8 @@ change. Use the locked public npm package when rebuilding these assets.

## Verification

Keep the canonical petstore totals unchanged: summary 42 changes / 18 breaking;
components summary 9/2 and raw JSON 10/3. Run cmd and full Go suites, race checks
Keep the canonical petstore totals unchanged: summary 45 changes / 19 breaking;
components 10/3 in both summary and raw JSON. Run cmd and full Go suites, race checks
on dispatch/policy/history, and command smoke checks. Compare
`BenchmarkOpenAPIReport` against the base branch with the same Go toolchain and
hardware; use `-benchmem` and multiple samples. The model-window test verifies
Expand Down
4 changes: 2 additions & 2 deletions .ai-docs/compact-report.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ The report contains the total and breaking change counts, up to eight semantic
breaking highlights from Doctor, and a link to the public Doctor page. Each
highlight is limited to 300 characters. If Doctor supplies no highlight for a
whole-object removal, the report shows its changed path and property. Spec text cannot inject Markdown links,
HTML, or mentions. Counts use the same JSONPath + property deduplication as
HTML, or mentions. Counts use the same deduplication as
`summary`. Existing detailed Markdown and raw JSON reports do not change.

A successful comparison always writes the compact report, including when no
Expand All @@ -28,7 +28,7 @@ The optional `--result-file` requires `--compact`. It writes this JSON only afte
the comparison and Markdown write succeed:

```json
{"total":42,"breaking":18}
{"total":45,"breaking":19}
```

Use a fresh result path for each run and require command success before reading
Expand Down
6 changes: 4 additions & 2 deletions .ai-docs/component-report-identity.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,9 @@

`summary`, `markdown-report`, and `html-report` use the shared
`internal/changecounts.Deduplicate` helper for their counts and change lists.
The helper keeps one change per semantic JSONPath and property.
The helper keeps one change per semantic edit: the JSONPath, property, change
type, and values together. Two edits to one property, such as an enum addition
and removal, stay separate so a breaking change is never hidden.

Doctor reports component additions and removals at `$.components`, with the
category in `property` and the component name in `new` or `original`. Before
Expand All @@ -15,6 +17,6 @@ list use this same list. The raw doctor tree remains intact for the document
view and the separate explorer graph. Machine-readable `report` output is
unchanged and retains the original engine paths.

The canonical petstore fixture still has 42 deduplicated changes, including 18
The canonical petstore fixture has 45 deduplicated changes, including 19
breaking changes. `cmd/component_report_test.go` covers additions and removals
across component categories through HTML, summary, and Markdown reports.
14 changes: 7 additions & 7 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ All `cmd/` implementation files use their canonical names (e.g., `cmd/summary.go
### Counts and semantics

- `summary` is the semantic human report.
- `summary` headline, highlights, and visible summary counts are deduplicated by `JSONPath + property`.
- `summary` headline, highlights, and visible summary counts count each edit once, matching on JSONPath, property, change type, and values.
- `markdown-report` top summary and object stats are also deduplicated.
- `report` is the machine-readable JSON interface and should prefer stable semantic identity over renderer-local structure.

Expand Down Expand Up @@ -139,20 +139,20 @@ After running `summary` on the petstore fixtures, the deduplicated counts must b

| Document Element | Total Changes | Breaking Changes |
|---|---|---|
| components | 9 | 2 |
| components | 10 | 3 |
| info | 4 | 0 |
| paths | 28 | 16 |
| paths | 30 | 16 |
| tags | 1 | 0 |

**Summary totals (deduplicated):**
- 42 total changes, 18 breaking
- Additions: 12, Modifications: 20, Removals: 10
- Breaking Modifications: 8, Breaking Removals: 10
- 45 total changes, 19 breaking
- Additions: 14, Modifications: 20, Removals: 11
- Breaking Modifications: 8, Breaking Removals: 11

**Report JSON totals (raw, not deduplicated):**
- Components: 10 total / 3 breaking

The `report` JSON numbers are intentionally higher than `summary` because summary deduplicates by `JSONPath + property`. This difference is correct behavior, not a bug. If these counts drift after a change, the change broke semantics.
`summary` only removes repeats of one edit, matching on JSONPath, property, change type, and values. `report` JSON keeps every occurrence, so it can be higher when a shared reference repeats an edit; for petstore the two match. Never deduplicate on JSONPath and property alone: an enum addition and removal share both, and that key hid breaking changes, including the removal of `Pet.name`. If these counts drift after a change, the change broke semantics.

## Validation Workflow

Expand Down
2 changes: 1 addition & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ COPY html-report/ui/src ./src
RUN npm ci
RUN npm run build

FROM --platform=$BUILDPLATFORM golang:1.26.9-bookworm AS builder
FROM --platform=$BUILDPLATFORM golang:1.26.10-bookworm AS builder

ARG TARGETPLATFORM
ARG BUILDPLATFORM
Expand Down
34 changes: 18 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,18 +20,26 @@ It can render the same semantic change model as:
- a markdown report
- a self-contained offline HTML report

The same commands accept both formats, including git history and revision-scoped
references. Each comparison must use the same format on both sides. AsyncAPI 2.x
and mixed OpenAPI/AsyncAPI comparisons are rejected.
It works well for local exploration, CI/CD checks, release notes, and API review workflows.

---

## AsyncAPI has landed

Event-driven APIs break too. They just do it quietly, in a consumer nobody remembers subscribing to that topic.

`openapi-changes` now speaks **AsyncAPI 3.x** natively. Same commands, same reports, same time machine.

```sh
openapi-changes summary previous-asyncapi.yaml asyncapi.yaml
openapi-changes report HEAD~1:asyncapi.yaml HEAD:asyncapi.yaml
openapi-changes html-report --report-file changes.html previous-asyncapi.yaml asyncapi.yaml
```

Existing breaking-rule files retain their OpenAPI meaning. To configure both
engines, use named sections:
The format is detected from the document, including across git history and revision-scoped references. Both sides of
a comparison must use the same format, and AsyncAPI 2.x is not supported.

Existing rule files keep their OpenAPI meaning. To configure both engines, use named sections:

```yaml
openapiRules:
Expand All @@ -41,21 +49,14 @@ openapiRules:
asyncapiRules:
channel:
address:
modified: true
multiFormatSchema:
modified: true
modified: false
schemaRules:
schema:
description:
type:
modified: false
```

`schemaRules` applies to JSON Schemas in AsyncAPI. Foreign schema languages are
compared as opaque content; changing their format or content is breaking by
default. JSON and HTML report items include format and version metadata in
`specification`. Human counts remain deduplicated; JSON retains raw changes.

It works well for local exploration, CI/CD checks, release notes, and API review workflows.
**[Read the AsyncAPI docs >](https://pb33f.io/openapi-changes/asyncapi/)**

## How is it the 'most powerful and complete?'?

Expand Down Expand Up @@ -194,6 +195,7 @@ multi-file specs with `$ref` references resolved from the same revision.
Full docs: https://pb33f.io/openapi-changes/

- [Installing openapi-changes](https://pb33f.io/openapi-changes/installing/)
- [Comparing AsyncAPI specifications](https://pb33f.io/openapi-changes/asyncapi/)
- [Configuring breaking changes](https://pb33f.io/openapi-changes/configuring/)
- [Command arguments](https://pb33f.io/openapi-changes/command-arguments/)
- Commands:
Expand All @@ -210,7 +212,7 @@ Full docs: https://pb33f.io/openapi-changes/

## Build from source

`openapi-changes` currently requires Go `1.26.9+`. The npm installer requires Node.js `20+`.
`openapi-changes` currently requires Go `1.26.10+`. The npm installer requires Node.js `20+`.

The report UI uses Node.js `24.15+` in the Node 24 release line. Run `npm ci`,
`npm run typecheck`, `npm test`, and `npm run build` in `html-report/ui` after
Expand Down
2 changes: 1 addition & 1 deletion cmd/compact_report.go
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ func renderCompactMarkdown(outcome compactOutcome, highlights []string) []byte {
default:
fmt.Fprintf(&sb, "**Total changes: %d. Breaking changes: %d.**\n\n", outcome.Total, outcome.Breaking)
}
sb.WriteString("Counts are deduplicated by JSONPath + property.\n\n")
sb.WriteString("Repeats of the same change are counted once.\n\n")
if len(highlights) > 0 {
sb.WriteString("### Breaking highlights\n\n")
for _, item := range highlights {
Expand Down
6 changes: 3 additions & 3 deletions cmd/compact_report_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@ func TestCompactReportPetstore(t *testing.T) {
require.NoError(t, err)
report, outcome, err := generateCompactMarkdown(commits, nil)
require.NoError(t, err)
assert.Equal(t, compactOutcome{Total: 42, Breaking: 18}, outcome)
assert.Contains(t, string(report), "**Total changes: 42. Breaking changes: 18.**")
assert.Equal(t, compactOutcome{Total: 45, Breaking: 19}, outcome)
assert.Contains(t, string(report), "**Total changes: 45. Breaking changes: 19.**")
assert.Contains(t, string(report), "### Breaking highlights")
assert.Contains(t, string(report), "https://pb33f.io/doctor/")
assert.NotContains(t, string(report), "Commit")
Expand Down Expand Up @@ -100,7 +100,7 @@ func TestCompactReportCommandBreakingHasCompletedOutcome(t *testing.T) {
require.NoError(t, command.Execute())
data, err := os.ReadFile(result)
require.NoError(t, err)
assert.JSONEq(t, `{"total":42,"breaking":18}`, string(data))
assert.JSONEq(t, `{"total":45,"breaking":19}`, string(data))
}

func TestCompactReportRejectsAliasedOutputs(t *testing.T) {
Expand Down
64 changes: 64 additions & 0 deletions cmd/enum_dedup_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
// Copyright 2023-2026 Princess Beef Heavy Industries, LLC / Dave Shanley
// SPDX-License-Identifier: Apache-2.0

package cmd

import (
"os"
"path/filepath"
"strings"
"testing"

"github.com/pb33f/testify/assert"
"github.com/pb33f/testify/require"
)

func TestEnumEditKeepsItsBreakingRemoval(t *testing.T) {
for name, spec := range map[string]string{
"asyncapi": `asyncapi: 3.0.0
info:
title: enum
version: 1.0.0
channels:
orders:
address: orders
messages:
created:
payload:
type: string
enum: [a, b]
`,
"openapi": `openapi: 3.1.0
info:
title: enum
version: 1.0.0
paths: {}
components:
schemas:
Status:
type: string
enum: [a, b]
`,
} {
t.Run(name, func(t *testing.T) {
assertEnumEdit(t, spec)
})
}
}

func assertEnumEdit(t *testing.T, spec string) {
t.Helper()
dir := t.TempDir()
left := filepath.Join(dir, "left.yaml")
right := filepath.Join(dir, "right.yaml")
require.NoError(t, os.WriteFile(left, []byte(spec), 0o644))
require.NoError(t, os.WriteFile(right, []byte(strings.Replace(spec, "[a, b]", "[a, c]", 1)), 0o644))

commits, err := loadLeftRightCommits(left, right, summaryOpts{noColor: true})
require.NoError(t, err)
_, outcome, err := generateCompactMarkdown(commits, nil)
require.NoError(t, err)

assert.Equal(t, 2, outcome.Total)
assert.Equal(t, 1, outcome.Breaking)
}
22 changes: 13 additions & 9 deletions cmd/markdown_report.go
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ func generateMarkdownReport(commits []*model.Commit, breakingConfig *whatChanged
successCount := 0
comparedCount := 0
var renderErrors []error
headerWritten := false
apiLabel := ""
includeCommitMetadata := true

for i, commit := range commits {
Expand All @@ -105,13 +105,7 @@ func generateMarkdownReport(commits []*model.Commit, breakingConfig *whatChanged
continue
}

// Write header on first success
if !headerWritten {
sb.WriteString("# " + commit.APILabel() + " Changes Report\n\n")
sb.WriteString(fmt.Sprintf("*Generated: %s*\n\n", time.Now().Format(time.RFC3339)))
headerWritten = true
}

apiLabel = mergeAPILabel(apiLabel, commit.APILabel())
successCount++
if successCount == 1 {
includeCommitMetadata = !isSyntheticLeftRightCommit(commit)
Expand Down Expand Up @@ -156,7 +150,17 @@ func generateMarkdownReport(commits []*model.Commit, breakingConfig *whatChanged
if successCount == 0 {
return nil, nil
}
return []byte(sb.String()), nil
// The title waits for every commit because history can change format between revisions.
header := fmt.Sprintf("# %s Changes Report\n\n*Generated: %s*\n\n", apiLabel, time.Now().Format(time.RFC3339))
return []byte(header + sb.String()), nil
}

// mergeAPILabel keeps a shared format label and falls back to a neutral one when formats mix.
func mergeAPILabel(current, next string) string {
if current == "" || current == next {
return next
}
return "API"
}

func GetMarkdownReportCommand() *cobra.Command {
Expand Down
30 changes: 30 additions & 0 deletions cmd/markdown_report_label_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
// Copyright 2023-2026 Princess Beef Heavy Industries, LLC / Dave Shanley
// SPDX-License-Identifier: Apache-2.0

package cmd

import (
"strings"
"testing"

"github.com/pb33f/testify/assert"
"github.com/pb33f/testify/require"
)

func TestMergeAPILabel(t *testing.T) {
assert.Equal(t, "OpenAPI", mergeAPILabel("", "OpenAPI"))
assert.Equal(t, "AsyncAPI", mergeAPILabel("AsyncAPI", "AsyncAPI"))
assert.Equal(t, "API", mergeAPILabel("OpenAPI", "AsyncAPI"))
assert.Equal(t, "API", mergeAPILabel("API", "OpenAPI"))
}

func TestMarkdownReportTitleForMixedFormats(t *testing.T) {
openapi, err := loadLeftRightCommits("../sample-specs/petstorev3-original.json", "../sample-specs/petstorev3.json", summaryOpts{noColor: true})
require.NoError(t, err)
asyncapi, err := loadLeftRightCommits("../sample-specs/asyncapi-original.yaml", "../sample-specs/asyncapi.yaml", summaryOpts{noColor: true})
require.NoError(t, err)

report, err := generateMarkdownReport(append(openapi, asyncapi...), nil, false)
require.NoError(t, err)
assert.True(t, strings.HasPrefix(string(report), "# API Changes Report\n"), "got: %.40s", report)
}
14 changes: 7 additions & 7 deletions cmd/markdown_report_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ func TestMarkdownReport_SingleCommitLeftRight(t *testing.T) {
content := string(report)
assert.True(t, strings.HasPrefix(content, "# OpenAPI Changes Report"))
assert.NotContains(t, content, "## Commit 1:")
assert.Contains(t, content, "**42** changes detected, **18** are **(💔 breaking)**.")
assert.Contains(t, content, "**45** changes detected, **19** are **(💔 breaking)**.")
}

func TestMarkdownReport_UsesDeduplicatedCounts(t *testing.T) {
Expand All @@ -127,10 +127,10 @@ func TestMarkdownReport_UsesDeduplicatedCounts(t *testing.T) {
require.NotNil(t, report)

content := string(report)
assert.Contains(t, content, "**42** changes detected, **18** are **(💔 breaking)**.")
assert.Contains(t, content, "- Additions: **12**")
assert.Contains(t, content, "**45** changes detected, **19** are **(💔 breaking)**.")
assert.Contains(t, content, "- Additions: **14**")
assert.Contains(t, content, "- Modifications: **20**")
assert.Contains(t, content, "- Removals: **10**")
assert.Contains(t, content, "- Removals: **11**")
}

func TestMarkdownReport_UsesDeduplicatedObjectStats(t *testing.T) {
Expand All @@ -150,8 +150,8 @@ func TestMarkdownReport_UsesDeduplicatedObjectStats(t *testing.T) {
assert.Contains(t, content, "| Operation | 5 | 2 |")
assert.Contains(t, content, "| PathItem | 9 | 5 |")
assert.Contains(t, content, "| Responses | 3 | 2 |")
assert.Contains(t, content, "| Schema | 10 | 4 |")
assert.Contains(t, content, "| Tag | 3 | 1 |")
assert.Contains(t, content, "| Schema | 11 | 5 |")
assert.Contains(t, content, "| Tag | 5 | 1 |")
assert.NotContains(t, content, "| Operation | 9 |")
assert.NotContains(t, content, "| PathItem | 9 | 6 |")
}
Expand All @@ -174,7 +174,7 @@ func TestMarkdownReport_LeftRightOmitsSyntheticCommitMetadata(t *testing.T) {
assert.NotContains(t, content, "- **Hash**:")
assert.NotContains(t, content, "- **Author**:")
assert.NotContains(t, content, "- **Date**:")
assert.Contains(t, content, "**42** changes detected, **18** are **(💔 breaking)**.")
assert.Contains(t, content, "**45** changes detected, **19** are **(💔 breaking)**.")
}

func TestMarkdownReport_PartialFailureReturnsPartialResults(t *testing.T) {
Expand Down
Loading
Loading