Handle equivalent duplicate schemas in multi-spec merge

[christianhelle]

Closes #1075

Summary

Fix multi-spec OpenAPI merging so Refitter accepts equivalent duplicate schemas instead of failing on them as collisions.

This resolves the test\multiple-sources.refitter scenario where the e-conomic OpenAPI specs like economic-products.json and economic-webhooks.json both define shared schemas such as Error and ProblemDetails.

What changed

• Added canonical equivalence checks for duplicate merged schemas.
• Preserved fail-fast behavior for true merge conflicts.
• Added regression tests for equivalent duplicate schema handling and the real e-conomic repro.

Why

The input specs are valid as-is and should not need local edits. Refitter should merge equivalent shared schemas without requiring changes to the upstream e-conomic OpenAPI documents.

Validation

• Added/updated merge tests for equivalent duplicates
• Added regression coverage for the e-conomic multi-spec case

Summary by CodeRabbit

• Bug Fixes

  • Fixed multi-spec OpenAPI merging to correctly handle duplicate but semantically equivalent schemas, allowing proper document consolidation.

• New Features

  • Added economic webhooks API specification with webhook management and event type operations.
  • Expanded multi-spec test configuration to include economic product and webhook specifications.

• Documentation

  • Added troubleshooting guide for multi-source OpenAPI tooling diagnostics.
  • Added implementation session logs and decision records.

• Tests

  • Expanded merge and schema-equivalence test coverage for multi-spec scenarios.
  • Renamed regression tests for clarity.
  • Added buildable validation for real-world multi-spec generation.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR implements a fix for multi-spec OpenAPI merge failures by replacing strict schema equivalence checking with canonical JSON token comparison. The solution accepts structurally identical duplicate schemas (like Error and ProblemDetails from economic-products.json and economic-webhooks.json) while preserving fail-fast behavior for genuine conflicts.

Changes

Cohort / File(s)	Summary
Core Merge Equivalence Implementation src/Refitter.Core/OpenApiDocumentFactory.cs	Replaces AreEquivalent string serialization with JToken.DeepEquals-based canonical comparison. Adds canonicalization utilities for OpenApiDocument, NSwag schema types, and NJsonSchema.JsonSchema with stable JSON generation (ordered properties, recursive schema inclusion, reference-identity placeholders). Tightens tag/schema merge guards using count-based initialization.
Merge Equivalence Test Coverage src/Refitter.Tests/OpenApiDocumentFactoryMergeTests.cs	Adds 739 lines of comprehensive merge and schema-equivalence tests covering: duplicate detection for structurally identical/recursive/composed schemas, canonicalization utility validation (nulls, extensions, references, cyclic handling), URL-decoding, normalization behaviors, and equivalence fallback behavior when canonicalization fails.
Economic Multi-Spec Regression Test src/Refitter.Tests/RegressionTests/MultiSpecSchemaMergeTests.cs	Renames test class and adds new test validating RefitGenerator.CreateAsync with real openApiPaths pointing to economic-products.json and economic-webhooks.json, including repository root discovery and buildable code compilation.
Test Class Renames src/Refitter.Tests/RegressionTests/*Tests.cs (6 files: ContractSuffixCorruptionTests, DynamicQuerystringMutationTests, EnumConverterInjectionTests, MalformedUnicodeEscapeTests, OneOfDiscriminatorNullRefTests, XmlDocEscapingTests)	Standardizes test class naming by removing Issue####_ prefix, improving clarity and decoupling test identity from issue numbers.
Economic OpenAPI Test Fixtures test/OpenAPI/v3.0/economic-webhooks.json, test/multiple-sources.refitter	Introduces complete Visma e-conomic webhooks API specification (v3.0.1) with 8 operations and 8 schema types including Webhook, ProblemDetails, and Error. Updates refitter configuration to include both economic-products.json and economic-webhooks.json.
Squad Team Documentation .squad/agents/*/history.md (ash, dallas, lambert, parker, ripley), .squad/decisions.md, .squad/log/2026-04-28T15-21-48+02-00-economic-openapi-implementation.md, .squad/orchestration-log/2026-04-28T15-21-48+02-00-*.md	Records investigation, decision, and implementation history for the merge equivalence fix including approved test strategy, validation evidence, and cross-agent coordination.
Diagnostic Guidance .squad/skills/multi-source-openapi-tooling/SKILL.md	New troubleshooting guide documenting OpenAPI path resolution, --skip-validation scope clarification, merge failure diagnosis, and anti-patterns for multi-spec .refitter tooling.

Sequence Diagram

sequenceDiagram
    participant Gen as RefitGenerator
    participant Merge as OpenApiDocumentFactory<br/>.Merge()
    participant Canon as Canonicalization<br/>Utilities
    participant Token as JToken<br/>Comparison

    Gen->>Merge: CreateAsync(multi-spec paths)
    Merge->>Merge: Process document 1,<br/>document 2
    Merge->>Merge: Detect duplicate<br/>schema name (Error)
    Merge->>Canon: AreEquivalent(schema1,<br/>schema2)
    Canon->>Canon: Normalize schema1<br/>to JToken
    Canon->>Canon: Normalize schema2<br/>to JToken
    Canon->>Token: JToken.DeepEquals
    Token-->>Canon: true (equivalent)
    Canon-->>Merge: true
    Merge->>Merge: Accept duplicate,<br/>skip merge
    Merge-->>Gen: Merged document<br/>(no conflict)
    Gen->>Gen: Generate code

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related issues

• Multi-spec merge fails on equivalent duplicate schemas #1075: This PR directly resolves the multi-spec merge failure where equivalent duplicate schemas (e.g., Error, ProblemDetails) were incorrectly treated as hard conflicts—the core issue being addressed.
• [v2.0 audit] Tracking epic — 46 findings since 1.7.3 #1057: Mentioned in vector search as related to the OpenApiDocumentFactory.Merge modifications for handling multi-spec merge collisions and equivalence logic.

Possibly related PRs

• [v2.0 audit] Fix pre-release regressions from #1057 #1064: Modifies OpenApiDocumentFactory.cs for multi-spec merge and validation hardening, sharing the same core file and domain.
• [v2.0 audit] Close remaining verified #1057 regressions #1070: Also targets OpenApiDocumentFactory merge/equivalence behavior with serialized JSON-based equivalence, overlapping domain and prior art.

Suggested labels

enhancement, .NET

Poem

🐰 Duplicate schemas, yet equiv-a-lent,
No longer clash—now merge is elegant!
Where cycles swirled and tokens danced,
Canonical JSON gives them a chance.
Conflicts stay strict, duplicates bend,
E-conomic specs now gracefully blend. 🌿✨

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Out of Scope Changes check	❓ Inconclusive	Several test class renames appear outside the stated scope of issue #1075's objectives (e.g., Issue1013/1014/1015/1035/1039 test class rename changes lack direct connection to duplicate schema handling).	Clarify whether the regression test class renames are intentional refactoring or should be separated into a distinct PR focusing on test naming conventions.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Handle equivalent duplicate schemas in multi-spec merge' clearly and concisely summarizes the main change: addressing duplicate schema handling in multi-spec OpenAPI merging.
Linked Issues check	✅ Passed	The PR fully addresses issue #1075 by implementing canonical OpenAPI-aware schema comparison, preserving fail-fast behavior for genuine conflicts, and adding comprehensive regression tests including the real e-conomic multi-spec scenario.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch economic-openapi

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/Refitter.Tests/RegressionTests/MultiSpecSchemaMergeTests.cs (1)

243-263: Add explicit fixture-existence assertions for clearer failures.

Right now missing files fail deeper in generation. A direct check near path construction gives faster and clearer diagnostics.

🧪 Suggested test-hardening diff

     public async Task Economic_OpenApiPaths_Generate_NonEmpty_Buildable_Code()
     {
         var repositoryRoot = GetRepositoryRoot();
         var productsSpec = Path.Combine(repositoryRoot, "test", "OpenAPI", "v3.0", "economic-products.json");
         var webhooksSpec = Path.Combine(repositoryRoot, "test", "OpenAPI", "v3.0", "economic-webhooks.json");
+        File.Exists(productsSpec).Should().BeTrue($"expected fixture at '{productsSpec}'");
+        File.Exists(webhooksSpec).Should().BeTrue($"expected fixture at '{webhooksSpec}'");
         var settings = new RefitGeneratorSettings
         {
             OpenApiPaths = [productsSpec, webhooksSpec],
             Namespace = "Economic"
         };

Based on learnings: "Test CLI changes with a real OpenAPI specification to ensure generation works correctly."

Also applies to: 292-302

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/Refitter.Tests/RegressionTests/MultiSpecSchemaMergeTests.cs` around lines
243 - 263, In the test Economic_OpenApiPaths_Generate_NonEmpty_Buildable_Code
add explicit assertions that the OpenAPI fixture files exist before calling
RefitGenerator.CreateAsync: after constructing productsSpec and webhooksSpec
assert File.Exists(productsSpec) and File.Exists(webhooksSpec) (or equivalent)
so failures fail fast and clearly; apply the same pattern to the other test that
uses OpenAPI fixture paths (the one around the second OpenApiPaths usage) to
ensure both specs are present before generation.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.squad/orchestration-log/2026-04-28T15-21-48+02-00-lambert.md:
- Around line 6-8: Update the log entry to use the current test filename instead
of the pre-rename name and fix the malformed generated-file path by restoring
the missing leading character; specifically replace the stale
"src\Refitter.Tests\RegressionTests\Issue1016_MultiSpecSchemaMergeTests.cs"
reference with the repository's current test path/name and change
"est\GeneratedCode\economic.cs" to the correct "test\GeneratedCode\economic.cs"
(or the actual expected generated-code path) so both entries reflect valid,
up-to-date paths.

---

Nitpick comments:
In `@src/Refitter.Tests/RegressionTests/MultiSpecSchemaMergeTests.cs`:
- Around line 243-263: In the test
Economic_OpenApiPaths_Generate_NonEmpty_Buildable_Code add explicit assertions
that the OpenAPI fixture files exist before calling RefitGenerator.CreateAsync:
after constructing productsSpec and webhooksSpec assert
File.Exists(productsSpec) and File.Exists(webhooksSpec) (or equivalent) so
failures fail fast and clearly; apply the same pattern to the other test that
uses OpenAPI fixture paths (the one around the second OpenApiPaths usage) to
ensure both specs are present before generation.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 4c2caf13-11e6-4239-b4f2-0af0d39cf994

📥 Commits

Reviewing files that changed from the base of the PR and between 6ebaec9 and 6639fb8.

📒 Files selected for processing (24)

• .squad/agents/ash/history.md
• .squad/agents/dallas/history.md
• .squad/agents/lambert/history.md
• .squad/agents/parker/history.md
• .squad/agents/ripley/history.md
• .squad/decisions.md
• .squad/log/2026-04-28T15-21-48+02-00-economic-openapi-implementation.md
• .squad/orchestration-log/2026-04-28T15-21-48+02-00-ash.md
• .squad/orchestration-log/2026-04-28T15-21-48+02-00-lambert.md
• .squad/orchestration-log/2026-04-28T15-21-48+02-00-parker.md
• .squad/skills/multi-source-openapi-tooling/SKILL.md
• src/Refitter.Core/OpenApiDocumentFactory.cs
• src/Refitter.Tests/OpenApiDocumentFactoryMergeTests.cs
• src/Refitter.Tests/RegressionTests/ContractSuffixCorruptionTests.cs
• src/Refitter.Tests/RegressionTests/DynamicQuerystringMutationTests.cs
• src/Refitter.Tests/RegressionTests/EnumConverterInjectionTests.cs
• src/Refitter.Tests/RegressionTests/MalformedUnicodeEscapeTests.cs
• src/Refitter.Tests/RegressionTests/MultiSpecSchemaMergeTests.cs
• src/Refitter.Tests/RegressionTests/OneOfDiscriminatorNullRefTests.cs
• src/Refitter.Tests/RegressionTests/XmlDocEscapingTests.cs
• test/OpenAPI/v3.0/economic-products.json
• test/OpenAPI/v3.0/economic-webhooks.json
• test/economic.refitter
• test/multiple-sources.refitter

[Copilot]

Pull request overview

Updates Refitter’s multi-spec OpenAPI merge to treat semantically equivalent duplicate schemas as non-conflicting (fixing the e-conomic multi-spec scenario) while keeping fail-fast behavior for true conflicts.

Changes:

• Implement canonical JSON-based equivalence checks for duplicate items during merge (with a schema fallback for cyclic graphs).
• Add merge/regression tests covering equivalent duplicate schemas and the real e-conomic multi-spec generation/buildability.
• Add e-conomic settings/spec inputs under test/ for repro/regression.

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
test/multiple-sources.refitter	Extends the sample multi-source settings to include the e-conomic specs.
test/economic.refitter	Adds a dedicated .refitter repro file for the e-conomic multi-spec case.
test/OpenAPI/v3.0/economic-webhooks.json	Adds the e-conomic webhooks OpenAPI document used in regression coverage.
src/Refitter.Core/OpenApiDocumentFactory.cs	Changes merge equivalence from serializer string compare to canonicalized JSON token comparison (plus schema fallback).
src/Refitter.Tests/OpenApiDocumentFactoryMergeTests.cs	Adds tests asserting equivalent duplicates are ignored (including recursive schema + Swagger2 definition coverage).
src/Refitter.Tests/RegressionTests/MultiSpecSchemaMergeTests.cs	Adds compile-backed regression for the real e-conomic multi-spec output and renames the test class.
src/Refitter.Tests/RegressionTests/XmlDocEscapingTests.cs	Renames regression test class.
src/Refitter.Tests/RegressionTests/OneOfDiscriminatorNullRefTests.cs	Renames regression test class.
src/Refitter.Tests/RegressionTests/MalformedUnicodeEscapeTests.cs	Renames regression test class.
src/Refitter.Tests/RegressionTests/EnumConverterInjectionTests.cs	Renames regression test class.
src/Refitter.Tests/RegressionTests/DynamicQuerystringMutationTests.cs	Renames regression test class.
src/Refitter.Tests/RegressionTests/ContractSuffixCorruptionTests.cs	Renames regression test class.
.squad/skills/multi-source-openapi-tooling/SKILL.md	Adds internal squad skill notes related to multi-source OpenAPI tooling.
.squad/orchestration-log/2026-04-28T15-21-48+02-00-parker.md	Adds squad orchestration log (gitignored path).
.squad/orchestration-log/2026-04-28T15-21-48+02-00-lambert.md	Adds squad orchestration log (gitignored path).
.squad/orchestration-log/2026-04-28T15-21-48+02-00-ash.md	Adds squad orchestration log (gitignored path).
.squad/log/2026-04-28T15-21-48+02-00-economic-openapi-implementation.md	Adds squad session log (gitignored path).
.squad/decisions.md	Records the e-conomic merge decision/validation notes.
.squad/agents/ripley/history.md	Updates agent history with e-conomic merge notes.
.squad/agents/parker/history.md	Updates agent history with e-conomic merge notes.
.squad/agents/lambert/history.md	Updates agent history with e-conomic merge notes.
.squad/agents/dallas/history.md	Updates agent history with e-conomic merge notes.
.squad/agents/ash/history.md	Updates agent history with e-conomic merge notes.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.14%. Comparing base (2e9d875) to head (ce3efd0).
⚠️ Report is 25 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1076      +/-   ##
==========================================
- Coverage   95.40%   95.14%   -0.27%     
==========================================
  Files          27       27              
  Lines        2437     2326     -111     
==========================================
- Hits         2325     2213     -112     
- Misses         39       43       +4     
+ Partials       73       70       -3     

Flag	Coverage Δ
unittests	95.14% <100.00%> (-0.27%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
1.6% Duplication on New Code

See analysis details on SonarQube Cloud

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/Refitter.Core/OpenApiDocumentFactory.cs`:
- Around line 326-327: The enum and composed-schema arrays aren’t canonicalized,
so reorderings cause false mismatches; when building schema JSON in
OpenApiDocumentFactory (the spot that currently sets json["enum"] from
actualSchema.Enumeration and the blocks that add "allOf","oneOf","anyOf" around
lines handling composed schemas), sort enum values and sort composed-schema
entries deterministically before adding them to the JArray (e.g. by stable
serialization or a comparer that canonicalizes each schema token), and replace
the direct Select/ToObject insertion with the sorted sequence so enum and
composed arrays are order-independent; apply the same deterministic ordering
logic to the other composed-schema handling at the other block (the one
referenced around lines 353-360).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a521f332-1455-40e7-80e1-8a8d7747e823

📥 Commits

Reviewing files that changed from the base of the PR and between 6639fb8 and ce3efd0.

📒 Files selected for processing (2)

• src/Refitter.Core/OpenApiDocumentFactory.cs
• src/Refitter.Tests/OpenApiDocumentFactoryMergeTests.cs

🚧 Files skipped from review as they are similar to previous changes (1)

• src/Refitter.Tests/OpenApiDocumentFactoryMergeTests.cs