Fix #41: gate match-analysis-type smart collection on FCPXML version

[leogdion]

Closes #41.

Problem

Defaults.smartCollections() unconditionally emitted a Missing Analysis smart collection containing <match-analysis-type>. That element does not exist in the FCPXML 1.13 DTD, verified against Apple's shipped DTDs:

$ grep -c match-analysis-type FCPXMLv1_13.dtd   # 0
$ grep -c match-analysis-type FCPXMLv1_14.dtd   # 5

The library default is FCPXMLVersion.supportedGeneration, which is 1.13, so every DSL document exported at the default version was invalid against Final Cut's own DTD. The fcpxml-dsl CLI defaults to 1.14, which is why the common path validated and this went unnoticed.

Approach

The version is only known inside export(version:), which runs after the whole library is built. Rather than post-processing the built model, the target version now rides on ResourceStore — already threaded inout through every build call, so it is the natural ambient-context channel. There is exactly one ResourceStore() call site in the codebase, so a defaulted init(version:) keeps everything compiling.

Gating uses the existing FCPXMLVersion.compatibility(relativeTo:) rather than string-matching a version number.

Why gated rather than dropped

The issue suggests "drop it as multicam did" as an option. That would break two green tests: all three feature-pair tests export at 1.14, and both real Final Cut fixtures (transitions/after.fcpxml:82, titles/after.fcpxml:61) do contain Missing Analysis. The structural diff runs in .symmetric mode, so removing the element from generated output is a reported difference. The multicam precedent does not transfer — multicam has no parity test pinning it to a real export.

Note for reviewers

The default (1.13) export now emits five smart collections rather than six. That is the fix. 1.14 output is unchanged.

Also extracts the previously private assertDTDValidates helper into a shared DTDValidationSupport.swift, since sibling branches need it too.

Verification

• FCPKIT_REQUIRE_DTD=1 swift test — 68 XCTest + 49/12/19 Swift Testing, all passing
• fcpxml-diff schema-completeness --fail-if-total-exceeds 0 — no structural loss
• swift-format lint and swiftlint — clean

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 479f3dde-b57c-4aee-995b-1c2323b1d574

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

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.}

[leogdion]

no global properties or functions

[leogdion]

Done in 6c0227d. softPromote and its four private helpers are now statics on a SoftPromote enum.

I renamed the entry point to promote(_:resources:) — as library(_:resources:) it would have overloaded the private library(for:version:) helpers it calls, which read badly.

This one predates the branch, but I converted it here rather than leave it as an exception to the rule. Same treatment on #43 and #44; FCPKitDSL now has no top-level functions.

[leogdion]

Done in 2d79e24. SoftPromote is gone; it is now Built.promotedLibrary(resources:).

You were right that it read as an anti-pattern. Looking at what it actually does — each Built case enters a fixed ladder at its own rung and folds upward, item → spine → sequence → project → event → library — it is plainly an operation on Built, not a bag of functions that happened to need a home.

I did not use a protocol here: one implementation, closed case set. AnchorableItem on #43 does get one, because it has four real conformers and collapses a genuine duplication. Happy to revisit if you'd rather see a protocol seam for testability.

Defaults went too, split along the seam it was hiding — two concerns that shared nothing but a file:

• version-gated vocabulary → FCPXMLVersion.admitsAnalysisMatching / .defaultSmartCollections (depended on nothing but the version)
• the sequence factory → ModelSequence.init(packing:format:) on the model type it constructs

Two incidental fixes fell out: the .event arm no longer inlines FCPKit.Library(...) instead of calling its own helper, and the .item arm no longer packs twice.

Also adopted typed throws across the module per your other note — throws(BuildError) end to end. It immediately earned its keep: it caught ResourceStore.format and the whole Layout chain still being untyped, which I'd have missed by eye.

Repo-wide namespace audit filed as #46, typed throws for the other modules as #47.