docs: update documentation to reflect the new diff package (#180)

Signed-off-by: Frédéric BIDON <fredbi@yahoo.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: fredbi

.claude/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Go library for analyzing, flattening, merging (mixin), and fixing
+Go library for analyzing, diffing, flattening, merging (mixin), and fixing
 [Swagger 2.0](https://swagger.io/specification/v2/) specifications. Built on top of
 `go-openapi/spec`, it is a central utility in the go-swagger ecosystem for code generation
 and validation tooling.
@@ -28,6 +28,17 @@ See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, an
 | `errors.go` | Sentinel errors (`ErrAnalysis`, `ErrNoSchema`) and error factory functions |
 | `debug.go` | Debug logger wired to `SWAGGER_DEBUG` env var |
 
+### `diff/` package
+
+| File | Contents |
+|------|----------|
+| `diff/spec_analyser.go` | `SpecAnalyser` — walks two specs and collects differences by endpoint, schema, parameter, response |
+| `diff/reporting.go` | `Compare(spec1, spec2 *spec.Swagger)` — top-level entry point returning `SpecDifferences` |
+| `diff/compatibility.go` | Backward-compatibility classification of each change |
+| `diff/spec_difference.go` | `SpecDifference`, `SpecDifferences`, `SpecChangeCode` — diff result types |
+| `diff/schema.go` | Schema-level diffing (properties, enums, allOf) |
+| `diff/checks.go` | Primitive comparisons: `CompareEnums()`, `CompareProperties()`, numeric range checks |
+
 ### Internal packages (`internal/`)
 
 | Package | Contents |
@@ -47,6 +58,7 @@ See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, an
 - `Schema(SchemaOpts) (*AnalyzedSchema, error)` — classify a schema (array, map, tuple, base type, etc.)
 - `Flatten(FlattenOpts) error` — flatten/expand a spec (inline schemas → definitions, remote refs → local)
 - `Mixin(primary, mixins...) []string` — merge multiple specs, returning collision warnings
+- `diff.Compare(spec1, spec2 *spec.Swagger) (SpecDifferences, error)` — compare two specs and report changes with compatibility info
 - `FixEmptyResponseDescriptions(*spec.Swagger)` — patch empty response descriptions
 
 ### Dependencies

.github/copilot-instructions.md

@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-Go library for analyzing, flattening, merging (mixin), and fixing
+Go library for analyzing, diffing, flattening, merging (mixin), and fixing
 [Swagger 2.0](https://swagger.io/specification/v2/) specifications. Built on top of
 `go-openapi/spec`, it is a central utility in the go-swagger ecosystem for code generation
 and validation tooling.
@@ -16,6 +16,7 @@ and validation tooling.
 | `flatten.go` | `Flatten(FlattenOpts)` — multi-step pipeline: expand, normalize, name inline schemas, strip OAIGen, remove unused |
 | `mixin.go` | `Mixin(primary, mixins...)` — merges specs, returns collision warnings |
 | `fixer.go` | `FixEmptyResponseDescriptions()` — patches empty response descriptions |
+| `diff/` | `Compare(spec1, spec2)` — compares two specs and reports structural and compatibility changes |
 
 Internal packages live under `internal/` (debug, antest, flatten/{normalize,operations,replace,schutils,sortref}).
 
@@ -24,6 +25,7 @@ Internal packages live under `internal/` (debug, antest, flatten/{normalize,oper
 - `New(*spec.Swagger) *Spec` — build an analyzed index from a parsed spec
 - `Flatten(FlattenOpts) error` — flatten/expand a spec
 - `Mixin(primary, mixins...) []string` — merge multiple specs
+- `diff.Compare(spec1, spec2 *spec.Swagger) (SpecDifferences, error)` — compare two specs
 - `Schema(SchemaOpts) (*AnalyzedSchema, error)` — classify a schema
 
 ### Dependencies

README.md

@@ -12,7 +12,7 @@
 
 ---
 
-A foundational library to analyze an OAI specification document for easier reasoning about the content.
+A foundational library to analyze, diff, flatten, merge, and fix OAI specification documents for easier reasoning about the content.
 
 ## Announcements
 
@@ -38,6 +38,7 @@ go get github.com/go-openapi/analysis
 
 * An analyzer providing methods to walk the functional content of a specification
 * A spec flattener producing a self-contained document bundle, while preserving `$ref`s
+* A spec differ ("diff") to compare two specs and report structural and compatibility changes
 * A spec merger ("mixin") to merge several spec documents into a primary spec
 * A spec "fixer" ensuring that response descriptions are non empty