BrightDigit Swift package scaffolding

[leogdion]

What to build

Bring FCPKit in line with BrightDigit Swift package norms — CI, lint/format, and package hygiene — so every subsequent change lands against a green, reviewable pipeline instead of only local swift test.

Acceptance criteria

• GitHub Actions (or equivalent) build and test the package on the platforms FCPKit claims to support
• SwiftLint and SwiftFormat (or the current BrightDigit equivalents) are configured and runnable locally and in CI
• Supporting package metadata matches sibling BrightDigit libraries (e.g. SPI / coverage hooks where those are standard)
• swift test and the schema-completeness gate still pass after scaffolding lands
• ADR / NEXT_STEPS no longer treat CI as out of scope for v0.1.0 if this ticket ships in that release

Blocked by

None — can start immediately (parallel with Step 0).

References

• Plan: docs/planning/v0.1.0-first-working-version.md
• ADR: docs/adr/0002-create-first-ordered-typed-model.md
• Worktrees: docs/planning/v0.1.0-worktree-plan.md

[leogdion]

Session 1 (2026-07-29). First slice landed as PR #15 (v0.1-scaffold → v0.1.x, not merged).

Done

• swift-tools-version 6.1 → 6.4 + .swift-version. No language-mode pin needed — 6.4 did not trigger a Swift 6 strict-concurrency cascade, so the ~69 non-Sendable structs are a non-issue for the bump.
• canImport gating so FCPKitMediaTools and fcpxml-generator compile without Apple frameworks — the prerequisite for the house template's Ubuntu/Windows/Android/wasm legs.
• AGENTS.md + ADR 0002 corrected: new tests use Swift Testing.

Sizing evidence for the rest of #4

House convention (from brightdigit/Spinetail, SyndiKit): .github/workflows/<Repo>.yml (255 lines, all jobs delegating to brightdigit/swift-build@v1), .mise.toml pinning swiftlint/swift-format/periphery, .swiftlint.yml + Scripts/lint.sh, .spi.yml, codecov.yml, .devcontainer.

Two things make the remainder more than a copy-paste:

1. Strict lint backlog. LINT_MODE: STRICT with missing_docs, explicit_acl, one_declaration_per_file, indentation_width. Sources/FCPKit/FCPXML.swift is 549 lines with zero /// comments and 14 public structs in one file; ~69 public structs package-wide, 4-space indent vs. the house 2-space. First strict run will emit hundreds of violations.
2. CGSize is unresolved. FCPXMLUtilities.generateFormatName takes CGSize and is currently ungated on the assumption Linux Foundation vends it. Not verified — no swift:6.4 Linux image exists yet, and the nightly-image pull did not finish. First real CI run settles it; if it does not resolve, gate that member too.

Suggested split

• #4a (PR Swift 6.4 toolchain, cross-platform gating, and BrightDigit CI template (#4) #15) — toolchain + gating. ✅
• #4b — workflow template + tool pinning, matrix restricted to what passes.
• #4c — strict-lint adoption with a documented violation baseline (or a docs/ACL cleanup pass).

Next session

Frontier is unchanged for the model lane: #5 (Step 0 guardrails) and then #6, on the v0.1.x worktree. Note #5's spine-order test should use withKnownIssue { }, not XCTExpectFailure, under the new testing convention.

[leogdion]

Correction to my earlier comment — I sized this against Spinetail; SyndiKit is the more recent template and is what PR #15 now adopts. Two things change materially.

1. The tools-version decision was backwards

I set swift-tools-version: 6.4 reasoning that "the house template assumes 6.4." That is wrong in an important way: SyndiKit declares swift-tools-version:5.10 (plus a Package@swift-6.0.swift variant), and that low floor is precisely what lets one manifest serve a matrix spanning Swift 5.10 → 6.4. 6.4 is the newest leg tested, not the required baseline.

Per decision on this session, FCPKit keeps 6.4 and the matrix is trimmed to 6.4-only legs. That is a real coverage trade, recorded here so it is revisitable:

Dropped	Was
Ubuntu	5.10, 6.0, 6.1, 6.2, 6.3
Windows	6.3 release
Android	6.3
macOS	Xcode 15.4, 16.4, 26.6
Source-compat	the entire sweep (all six containers)

Every trimmed spot carries a comment. Restoring coverage = lower the tools-version (or add Package@swift-X.swift variants), then restore the version lists in configure, build-windows, build-android, .github/matrices/*.json, and swift-source-compat.yml.

visionOS is dropped for an unrelated reason: Package.swift does not declare that platform.

2. The lint backlog is bigger than I estimated

I said "hundreds." Measured against the actual house config:

Tool	Violations
SwiftLint --strict	1,522
swift-format --strict	6,060

Top SwiftLint rules: indentation_width (463), type_contents_order (389), trailing_whitespace (185), explicit_acl (145), one_declaration_per_file (93), line_length (69).

Most of that is auto-fixable, which suggests splitting the cleanup by risk rather than doing it in one pass.

Revised split

• #4a — toolchain + canImport gating ✅ (PR Swift 6.4 toolchain, cross-platform gating, and BrightDigit CI template (#4) #15, ccce64f)
• #4b — CI template adoption ✅ (PR Swift 6.4 toolchain, cross-platform gating, and BrightDigit CI template (#4) #15, c98aff0) — lint job red by design
• #4c — mechanical formatting: swiftlint --fix, swift-format --in-place. Large diff, near-zero risk.
• #4d — judgement rules: explicit_acl, one_declaration_per_file (14 public structs in FCPXML.swift alone), missing_docs.

Still open

CGSize in FCPXMLUtilities.generateFormatName is ungated on the assumption Linux Foundation vends it — unverified locally (no swift:6.4 Linux image exists yet). The Ubuntu leg on PR #15 settles this; if it fails, gate that member too.

[leogdion]

Session 1 handoff (2026-07-29)

All work is in PR #15 (v0.1-scaffold → v0.1.x, 6 commits, not merged).

CI state at end of session

Job	Status
Configure Matrix	✅
Build on macOS (xcode-27)	✅
Build on Ubuntu (noble, 6.4)	✅ 54/58 tests (4 AVFoundation ones gate out)
Build on Ubuntu wasm / wasm-embedded	⏳ awaiting result of the checksum fix in fe8c823
Windows / Android	skipped (full-matrix tier only — runs on PRs into main/semver)
Linting	🔴 not yet reached; will fail — see below

Four rounds of CI fixes were needed; each problem was invisible to inspection:

1. XMLParser is in FoundationXML on Linux, not Foundation
2. MulticamXMLBuilderTests / TypedGenerationTests import AVFoundation (missed initially because my Docker check ran swift build without --build-tests)
3. testValidateThrowsWhenDTDMissing assumed xmllint exists — validate() checks for it before the DTD lookup
4. wasm SDK snapshot predated the nightly compiler; bumped to 2026-07-22

Immediate next step

Check the wasm legs on the latest run. If the checksum fix does not resolve them, set ENABLE_WASM=false — both SyndiKit and Spinetail already do exactly this (they pin the same stale 2026-06-15 SDK and never run the legs):

gh variable set ENABLE_WASM --repo brightdigit/FCPKit --body false

The lint backlog — the real remaining work

Measured, not estimated:

Tool	Violations
SwiftLint --strict	1,522
swift-format --strict	6,060

Top rules: indentation_width (463), type_contents_order (389), trailing_whitespace (185), explicit_acl (145), one_declaration_per_file (93), line_length (69).

Suggested split:

• #4c — mechanical formatting: swiftlint --fix, swift-format format --in-place. Huge diff, near-zero risk. Should land alone.
• #4d — judgement rules: explicit_acl, one_declaration_per_file (14 public structs in FCPXML.swift alone), missing_docs (549 lines, zero ///).

Also open

• Matrix is 6.4-only. FCPKit's swift-tools-version: 6.4 excludes Ubuntu 5.10–6.3, Windows 6.3, Android 6.3, macOS Xcode 15.4/16.4/26.6, and the whole source-compat sweep. SyndiKit gets full coverage via a 5.10 floor + Package@swift-6.0.swift. Worth deciding deliberately.
• Codecov — fail_ci_if_error is false because uploads 404 (repo not registered / no CODECOV_TOKEN). Flip back once configured.
• CMTime in the public API — remove once FCPTime lands in Step 1: FCPTime and unused value types #6.

Model lane is untouched

#5 (Step 0 guardrails) and #6 remain the frontier on the v0.1.x worktree, which still needs creating (git trees add v0.1.x origin/v0.1.x). Note the new testing convention: #5's spine-order test should use withKnownIssue { }, not XCTExpectFailure.