UC-09: Compare Versions
When two refs, versions, or implementations need a rigorous behavioral comparison. Performs a bounded behavioral-equivalence check between side A and side B (side-effect diffs, exception-envelope diffs, and a dimension-by-dimension divergence matrix) and returns a structured verdict (equivalent, intentionally divergent, and so on).
What Makes It Different
- It reconciles both implementations against the semantic model and produces a witnessed equivalence verdict with a divergence matrix, not an impression.
- Ideal for refactor safety and for verifying that an AI-generated replacement preserves behavior.
- It labels which dimensions diverge and which are preserved.
Prompt
Run RubberDuck UC-09: Comparison. [EDIT INPUTS ONLY] target = <owner/repo or local path> branch = auto commit = latest side_a = <current behavior / ref> side_b = <diff / ref> [/EDIT INPUTS ONLY] Comparison only; do not edit repo. Required artifact: `COMPARISON_REPORT.md`. Use prod RD to validate applied/current side: `get_started`, completed `detailed_repo_analysis(..., semantic_mode="full")`, Phase 2 ready, `load_code(max_files=4000)`, current-ref source/graph evidence. Treat any supplied diff side as diff evidence, not applied code, unless the checkout is explicitly pinned to it. Stop if either side, ref proof, hard RD gate, or hidden hard primitive after 3 scoped retries is missing. Compare default behavior, compatibility, security invariant, remaining risky paths, exception/config drift, test adequacy, migration risk, and false assurance. Write `COMPARISON_REPORT.md`: scenario, equivalence verdict, side-by-side table, divergence risks, compatibility tests, falsification steps, method notes. Security artifact contract: include sections named Security Invariant, Adversarial Probes, Impact/Test Matrix, Evidence-Cleanliness Blockers, Unsupported Clean/Security-Ready Claims. State whether sides are equivalent, intentionally divergent, or blocked; do not claim full safety beyond compared evidence.
Input
Repo, branch/ref, commit, side A, side B.
Output
A comparison report with a verdict and a per-dimension divergence matrix.
With RubberDuck MCP: Cross-Builder Comparison in ~11 Tool Calls
| # | Tool Call | Result |
|---|---|---|
| 1 | load_code(repo="local/sphinx", subpath="sphinx/builders", max_files=15) | Multiple builder files loaded: HTML, Epub3, base Builder, gettext, dummy, etc. |
| 2 | read_source(function_name="prepare_writing", analysis_id="init_5") | Full 108-line HTML builder method (lines 428-535): search indexer, doc writer, global context |
| 3 | read_source(function_name="prepare_writing", analysis_id="epub3") | Full 8-line Epub3 method (lines 102-109): super() call + 4 context keys |
| 4 | assess(mode="diff", analysis_id_before="init_5", analysis_id_after="epub3") | Structural diff between the two builder files: symbol-level comparison |
| 5 | search_code(pattern="def prepare_writing", analysis_id="all") | 5 implementations found across 52 analyses, with enclosing_function annotations |
| 6 | query_action(action="shared_variables", analysis_id="init_5", params={method_a: "prepare_writing", method_b: "second-method"}) | Shared state analysis for HTML builder's prepare_writing |
| 7 | query_action(action="call_chain", analysis_id="init_5", method="prepare_writing") | 24 callees verified: IndexBuilder, HTMLWriter, OptionParser, format_date, etc., coherence 1.0 |
| 8 | query_action(action="call_chain", analysis_id="epub3", method="prepare_writing") | 2 callees: super().prepare_writing() + THEME_WRITING_MODES.get() |
| 9 | search_code(pattern="THEME_WRITING_MODES", analysis_id="all") | 2 matches: definition at line 45 and usage at line 106 |
| 10 | read_source(start_line=115, end_line=180, analysis_id="epub3") | EpubBuilder base class: class attributes (copysource, embedded, search=False) |
| 11 | read_source(function_name="build_update") | Caller of prepare_writing: the build pipeline entry point |
Side-by-Side Comparison
StandaloneHTMLBuilder (108 lines, 428-535)
def prepare_writing(self, docnames):
# 1. Search indexer setup (conditional on self.search)
# 2. HTMLWriter + OptionParser initialization
# 3. Domain indices generation
# 4. "Last updated" date formatting
# 5. Logo/favicon URL handling
# 6. Document relations collection
# 7. Rellinks assembly
# 8. Script/CSS file backup
# 9. globalcontext dict creation (~30 keys)
# 10. Theme options merge
# 11. html_context mergeEpub3Builder (8 lines, 102-109)
def prepare_writing(self, docnames):
super().prepare_writing(docnames) # Gets all 108 lines above
writing_mode = self.config.epub_writing_mode
self.globalcontext['theme_writing_mode'] = THEME_WRITING_MODES.get(writing_mode)
self.globalcontext['html_tag'] = self.html_tag
self.globalcontext['use_meta_charset'] = self.use_meta_charset
self.globalcontext['skip_ua_compatible'] = TrueWhat Epub3 ADDS (4 keys to globalcontext)
| Key | Value | Purpose |
|---|---|---|
| theme_writing_mode | 'vertical-rl' or 'horizontal-tb' | CSS writing-mode for Japanese/Chinese vertical text |
| html_tag | EPUB3 namespace HTML tag | xmlns:epub="http://www.idpf.org/2007/ops" |
| use_meta_charset | True | <meta charset="utf-8"> for EPUB3 validation |
| skip_ua_compatible | True | Disables IE compatibility meta (not needed in EPUB) |
Call Chain Comparison (coherence 1.0 on both)
StandaloneHTMLBuilder.prepare_writing → 24 callees:
IndexBuilder, HTMLWriter, OptionParser, load_indexer,
format_date, _get_style_filename, collect_relations,
isurl, basename, sorted, isinstance, bool, list, update...
Epub3Builder.prepare_writing → 2 callees:
super().prepare_writing() → delegates to all 24 above
THEME_WRITING_MODES.get() → dict lookupAll 5 Implementations Found via search_code(analysis_id="all")
| Builder | File | Lines | Strategy |
|---|---|---|---|
| Builder (base) | __init__.py | 574 | Abstract: raise NotImplementedError |
| StandaloneHTMLBuilder | html/__init__.py | 428-535 | Full implementation (108 lines) |
| Epub3Builder | epub3.py | 102-109 | Extension via super() (8 lines) |
| TextBuilder | text.py | 63 | Simple: creates TextWriter |
| I18nBuilder | gettext.py | 140 | Empty: return |
Shared State Dependencies Mapped
| State | Created by HTML | Used by Epub3? |
|---|---|---|
| self.indexer | Conditional on self.search | No (EpubBuilder sets search = False) |
| self.docwriter | HTMLWriter(self) | Yes (inherited) |
| self.docsettings | OptionParser | Yes (inherited) |
| self.domain_indices | Generated from domains | Yes (inherited) |
| self.globalcontext | Dict with ~30 keys | Extended with 4 EPUB3 keys |
| self.relations | env.collect_relations() | Yes (inherited) |
Without RubberDuck MCP: Same Conclusion, More Manual Work
The AI read both files, grep for def prepare_writing across the codebase, read each builder file individually, and manually compared implementations.
| Gap | Detail |
|---|---|
| No verified call chain | Listed what prepare_writing "probably calls" based on reading, no formal dependency count. MCP's call_chain action returned 24 verified callees with coherence 1.0. |
| No structural diff | Compared implementations by reading both, no symbol-level structural comparison. MCP's assess(mode="diff") provided a formal structural diff. |
| No shared state verification | Described shared state from reading: "globalcontext is shared." MCP's shared_variables + call_chain formally mapped which state HTML creates, which Epub3 inherits. |
| No THEME_WRITING_MODES tracing | Mentioned the constant but didn't verify where it's defined. MCP's search_code found both the definition (line 45) and usage (line 106) in one call. |
Comparison Table
| Dimension | With RubberDuck MCP | Without MCP |
|---|---|---|
| Implementations found | 5 across 52 analyses: 1 search call | 6 across builder files: 6+ file reads |
| Call chain (HTML) | 24 callees, coherence 1.0 | "It calls IndexBuilder, HTMLWriter, etc.", reading-based |
| Call chain (Epub3) | 2 callees, coherence 1.0 | "It calls super() and adds 4 keys", correct but unverified |
| Structural diff | assess(mode="diff"): symbol-level | Manual reading of both files |
| Shared state | Formally mapped: 6 attributes with create/inherit/extend status | Prose description: "globalcontext is shared" |
| Constant tracing | search_code found definition + usage in 1 call | Mentioned but not traced |
Bottom line: Both approaches correctly compare the two implementations and identify Epub3's 4 additions. But MCP's analysis is formally verified: call chains carry coherence 1.0, structural diffs are symbol-level, shared state is mapped with create/inherit/extend status.
Videos
With RubberDuck MCP
Same Sphinx repo, now comparing prepare_writing across StandaloneHTMLBuilder and Epub3Builder with both RubberDuck MCP servers enabled in Cursor. The agent calls load_repo, read_source, compare_snapshots, search_code, shared_variables, and call_chain directly against the semantic graph, and search_code alone surfaces all 5 implementations across 52 analyses in a single call. call_chain returns 24 verified callees for the HTML builder and 2 for Epub3, both at coherence 1.0, so the final verdict (Overall Risk LOW, no breaking changes, key collisions unlikely because EPUB3's keys are namespaced) rests on a formally traced call graph and shared state map, not a guess.
Without MCP
Same repo, same prompt, both MCP servers disabled in Cursor Settings. With no semantic tools to call, the agent launches a subagent that reads epub3.py by hand (lines 1 to 105) and greps for constants like html_tag, use_meta_charset, and THEME_WRITING_MODES to work out what Epub3Builder adds. It reaches a similar conclusion, a shared state table and a list of 7 builder implementations including TextBuilder and XMLBuilder that the MCP run never surfaced, but every dependency in it (self.docwriter, self.domain_indices, and the rest) is inferred from reading source, not verified against a call graph or a coherence score.