Build the template engine — board-as-template instantiation
A template is a board folder the ordinary loader reads — no second schema, no Swift catalog. BoardTemplate became exactly that: a loaded BoardModel with chooser-facing derivations, the lane-title stub gone. TemplateEngine instantiates by the copy-remint-restamp walk: .git and .trash excluded at top level only — both names mean something at a board root and nowhere else, and .gitignore must survive — every materialized folder reminted, created/modified stamped fresh (born today, not forked), modified-by cleared, the template: key carried inert, the blurb and style inherited, and loose card files normalized at this import boundary per the paste precedent so a new board never opens with a notice about a mess its own birth made. Legacy deleted: keys copy through verbatim to the one migrator — stripping would resurrect, skipping would destroy. Atomicity is construct-then-clean: a sibling temp can be sandbox-refused and a cross-volume rename is just a second copy, so the call removes what it created on every non-board exit and never touches an occupied destination. The cancellable per-item walk extracted into BoardTreeCopy serves Duplicate and instantiation with two parameters — top-level exclusions and folder-attribute carriage, the only axes they differ on. Claude-Session: https://claude.ai/code/session_01SR4XGjmBE16ZUYWpfFHXwY
This commit is contained in:
@@ -2,118 +2,168 @@ import Foundation
|
||||
import Testing
|
||||
@testable import Kanban
|
||||
|
||||
/// Template instantiation — the on-disk half of File ▸ New Board… (09-templates.md ▸ Instantiation).
|
||||
/// Template **discovery** — the bundled store, and what a `BoardTemplate` reads off a real board
|
||||
/// folder (09-templates.md ▸ Definition format).
|
||||
///
|
||||
/// The window flow around it (the chooser, `NSSavePanel`, the open that follows) is untestable
|
||||
/// without a screen and deliberately holds no rules of its own; everything that *is* a rule — what
|
||||
/// gets written, what the board is called, and the order the lanes land in — lives in
|
||||
/// `BoardTemplate.instantiate(at:)` and is checked here against a real temp folder, through the
|
||||
/// app's own loader.
|
||||
|
||||
// MARK: - Fixtures
|
||||
|
||||
/// An empty temp folder to create *into* — the save panel's answer, minus the panel.
|
||||
private func temporaryLocation(named name: String) throws -> (url: URL, tearDown: () -> Void) {
|
||||
let container = FileManager.default.temporaryDirectory
|
||||
.appendingPathComponent("BoardTemplateTests-\(UUID().uuidString)", isDirectory: true)
|
||||
try FileManager.default.createDirectory(at: container, withIntermediateDirectories: true)
|
||||
return (container.appendingPathComponent(name, isDirectory: true), {
|
||||
try? FileManager.default.removeItem(at: container)
|
||||
})
|
||||
}
|
||||
/// The instantiation half lives in `TemplateEngineTests.swift`. What this file pins is 09's
|
||||
/// "testable for free" clause: "template validity is enforced by the loader's own fail-fast rules at
|
||||
/// test time (walk `Templates/`, load each)".
|
||||
|
||||
// MARK: - Tests
|
||||
|
||||
@Suite("BoardTemplate")
|
||||
struct BoardTemplateTests {
|
||||
|
||||
@Test("Basic writes a board and its three lanes, in order")
|
||||
func basicInstantiatesInOrder() throws {
|
||||
let location = try temporaryLocation(named: "Roadmap.kanban")
|
||||
defer { location.tearDown() }
|
||||
@Test("Every bundled template folder loads through the ordinary loader")
|
||||
func everyBundledTemplateLoads() throws {
|
||||
let store = try #require(TemplateEngine.bundledStore)
|
||||
let folders = TemplateEngine.templateFolders(in: store)
|
||||
#expect(!folders.isEmpty, "the app ships at least one template")
|
||||
|
||||
try BoardTemplate.basic.instantiate(at: location.url)
|
||||
|
||||
let result = try BoardLoader.load(boardRoot: location.url)
|
||||
#expect(result.warnings.isEmpty, "a board this app just wrote must load clean")
|
||||
#expect(result.model.lanes.map { $0.title.value } == ["To Do", "Doing", "Done"])
|
||||
#expect(result.model.lanes.allSatisfy { !$0.isDeleted })
|
||||
#expect(result.model.lanes.allSatisfy { $0.cards.isEmpty }, "the Basic scaffold seeds no cards")
|
||||
for folder in folders {
|
||||
let result = TemplateEngine.load(templateAt: folder, origin: .bundled)
|
||||
if case let .failure(error) = result {
|
||||
Issue.record("bundled template \(folder.lastPathComponent) failed to load: \(error.description)")
|
||||
}
|
||||
}
|
||||
#expect(TemplateEngine.bundledTemplates().count == folders.count)
|
||||
}
|
||||
|
||||
@Test("The lanes are ranked by the board convention — 1024 apart, from 1024")
|
||||
func lanesAreRankedByTheAppendConvention() throws {
|
||||
let location = try temporaryLocation(named: "Ranked.kanban")
|
||||
defer { location.tearDown() }
|
||||
@Test("Basic is bundled, first, and the plain To Do / Done scaffold")
|
||||
func basicIsTheFirstBundledTemplate() throws {
|
||||
let basic = try #require(TemplateEngine.bundledTemplates().first)
|
||||
|
||||
try BoardTemplate.basic.instantiate(at: location.url)
|
||||
|
||||
let orders = try BoardLoader.load(boardRoot: location.url).model.lanes.map(\.order)
|
||||
#expect(orders == [1024, 2048, 3072], "each lane appends after the one before it")
|
||||
#expect(basic.slug == "basic", "09 calls the bundle folder name the template's stable slug")
|
||||
#expect(basic.origin == .bundled)
|
||||
#expect(basic.name == "Basic")
|
||||
#expect(basic.lanes.map { $0.title.value } == ["To Do", "Done"])
|
||||
#expect(basic.lanes.allSatisfy { $0.cards.isEmpty }, "the Basic scaffold seeds no cards")
|
||||
}
|
||||
|
||||
@Test("The board's title is the document name the user chose, not the template's")
|
||||
func titleComesFromTheChosenName() throws {
|
||||
let location = try temporaryLocation(named: "Q3 Planning.kanban")
|
||||
defer { location.tearDown() }
|
||||
@Test("Name, blurb, icon and chooser order all come off the template board's own index.md")
|
||||
func pickerMetadataIsReadFromTheBoard() throws {
|
||||
let basic = try #require(TemplateEngine.bundledTemplates().first)
|
||||
|
||||
try BoardTemplate.basic.instantiate(at: location.url)
|
||||
|
||||
// 01-storage-format.md § Board naming: display name and folder name start out matching.
|
||||
#expect(try BoardLoader.load(boardRoot: location.url).model.title.value == "Q3 Planning")
|
||||
#expect(basic.name == basic.model.title.value)
|
||||
#expect(!basic.blurb.isEmpty, "the body is the picker blurb and the new board's description")
|
||||
#expect(basic.blurb == basic.model.document.body.trimmingCharacters(in: .whitespacesAndNewlines))
|
||||
#expect(basic.icon == basic.model.icon.value)
|
||||
#expect(basic.iconColor == basic.model.iconColor.value)
|
||||
#expect(basic.order == 100, "template: {order: 100} is the chooser position")
|
||||
}
|
||||
|
||||
@Test("An extension-less location is as legal a board, and keeps its whole name as the title")
|
||||
func extensionlessLocationWorks() throws {
|
||||
let location = try temporaryLocation(named: "Plain")
|
||||
defer { location.tearDown() }
|
||||
@Test("An icon the running system cannot draw falls back to the board default")
|
||||
func unknownIconFallsBackToTheDefault() throws {
|
||||
let fixture = try TemplateFixture(named: "Odd Icon")
|
||||
defer { fixture.tearDown() }
|
||||
try fixture.board(icon: "not.a.real.symbol.name")
|
||||
|
||||
try BoardTemplate.basic.instantiate(at: location.url)
|
||||
let template = try fixture.template()
|
||||
|
||||
#expect(try BoardLoader.load(boardRoot: location.url).model.title.value == "Plain")
|
||||
#expect(template.icon == ItemSymbol.board)
|
||||
}
|
||||
|
||||
@Test("Every lane folder is a fresh lowercase UUID")
|
||||
func laneFoldersAreMintedIdentities() throws {
|
||||
let location = try temporaryLocation(named: "Minted.kanban")
|
||||
defer { location.tearDown() }
|
||||
// MARK: template.order
|
||||
|
||||
try BoardTemplate.basic.instantiate(at: location.url)
|
||||
@Test("A keyless board dropped in the store is a template with no order")
|
||||
func keylessTemplateHasNoOrder() throws {
|
||||
let fixture = try TemplateFixture(named: "Hand Dropped")
|
||||
defer { fixture.tearDown() }
|
||||
try fixture.board()
|
||||
|
||||
let ids = try BoardLoader.load(boardRoot: location.url).model.lanes.map(\.id.rawValue)
|
||||
#expect(ids.count == 3)
|
||||
#expect(Set(ids).count == 3, "three lanes, three identities")
|
||||
#expect(ids.allSatisfy { $0 == $0.lowercased() }, "the app emits lowercase UUIDs")
|
||||
#expect(ids.allSatisfy { UUID(uuidString: $0) != nil })
|
||||
#expect(try fixture.template().order == nil, "no template: key is required of a user template")
|
||||
}
|
||||
|
||||
@Test("Instantiating over an existing board refuses rather than clobbering it")
|
||||
func refusesToOverwriteAnExistingBoard() throws {
|
||||
let location = try temporaryLocation(named: "Taken.kanban")
|
||||
defer { location.tearDown() }
|
||||
try BoardTemplate.basic.instantiate(at: location.url)
|
||||
let before = try Data(contentsOf: location.url.appendingPathComponent("index.md"))
|
||||
@Test("A malformed template: key reads as keyless rather than as a failure")
|
||||
func malformedTemplateKeyIsKeyless() throws {
|
||||
let fixture = try TemplateFixture(named: "Odd Key")
|
||||
defer { fixture.tearDown() }
|
||||
try fixture.board(extraKeys: "template: [1, 2]")
|
||||
|
||||
let error = writeFailure { try BoardTemplate.basic.instantiate(at: location.url) }
|
||||
|
||||
#expect(error?.operation == .createBoard)
|
||||
#expect(
|
||||
try Data(contentsOf: location.url.appendingPathComponent("index.md")) == before,
|
||||
"the existing board is untouched — a create never replaces one"
|
||||
)
|
||||
#expect(try fixture.template().order == nil)
|
||||
}
|
||||
|
||||
@Test("The document name behind a chosen URL is the folder name without its extension")
|
||||
func documentNameStripsTheExtension() {
|
||||
#expect(BoardTemplate.documentName(of: URL(fileURLWithPath: "/Boards/Roadmap.kanban")) == "Roadmap")
|
||||
#expect(BoardTemplate.documentName(of: URL(fileURLWithPath: "/Boards/Roadmap")) == "Roadmap")
|
||||
@Test("A float order is as good as an integer one")
|
||||
func floatOrderReads() throws {
|
||||
let fixture = try TemplateFixture(named: "Float")
|
||||
defer { fixture.tearDown() }
|
||||
try fixture.board(extraKeys: "template: {order: 12.5}")
|
||||
|
||||
#expect(try fixture.template().order == 12.5)
|
||||
}
|
||||
|
||||
@Test("The chooser offers Basic, and Basic is first")
|
||||
func inventoryHoldsBasicFirst() {
|
||||
// m9-templates: this becomes the bundled inventory's ten, with Basic still first
|
||||
// (09-templates.md ▸ Inventory).
|
||||
#expect(BoardTemplate.all.first == BoardTemplate.basic)
|
||||
#expect(BoardTemplate.basic.slug == "basic")
|
||||
// MARK: Chooser order
|
||||
|
||||
@Test("Chooser order is template.order, then display name for the keyless tier")
|
||||
func chooserOrderIsKeyedThenNamed() throws {
|
||||
let fixture = try TemplateFixture(named: "Sorting")
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
let second = try fixture.freeStandingBoard(named: "b", title: "Second", extraKeys: "template: {order: 200}")
|
||||
let first = try fixture.freeStandingBoard(named: "a", title: "First", extraKeys: "template: {order: 100}")
|
||||
let zebra = try fixture.freeStandingBoard(named: "z", title: "Zebra")
|
||||
let apple = try fixture.freeStandingBoard(named: "y", title: "Apple")
|
||||
|
||||
let sorted = TemplateEngine.sortedForChooser([zebra, second, apple, first])
|
||||
|
||||
#expect(sorted.map(\.name) == ["First", "Second", "Apple", "Zebra"])
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Fixture
|
||||
|
||||
/// A temp store holding hand-written template board folders — the user store's shape, minus
|
||||
/// Application Support (which no test may touch).
|
||||
struct TemplateFixture {
|
||||
|
||||
let store: URL
|
||||
let boardURL: URL
|
||||
|
||||
init(named name: String) throws {
|
||||
store = FileManager.default.temporaryDirectory
|
||||
.appendingPathComponent("TemplateTests-\(UUID().uuidString)", isDirectory: true)
|
||||
boardURL = store.appendingPathComponent("\(name).kanban", isDirectory: true)
|
||||
try FileManager.default.createDirectory(at: store, withIntermediateDirectories: true)
|
||||
}
|
||||
|
||||
func tearDown() {
|
||||
try? FileManager.default.removeItem(at: store)
|
||||
}
|
||||
|
||||
/// The fixture's own board, with one lane so it is a board worth previewing.
|
||||
func board(title: String = "Fixture", icon: String? = nil, extraKeys: String = "") throws {
|
||||
try write(board: boardURL, title: title, icon: icon, extraKeys: extraKeys)
|
||||
}
|
||||
|
||||
/// A second board in the same store — the sorting tests need several.
|
||||
func freeStandingBoard(named name: String, title: String, extraKeys: String = "") throws -> BoardTemplate {
|
||||
let url = store.appendingPathComponent("\(name).kanban", isDirectory: true)
|
||||
try write(board: url, title: title, icon: nil, extraKeys: extraKeys)
|
||||
return try loadTemplate(at: url)
|
||||
}
|
||||
|
||||
func template() throws -> BoardTemplate {
|
||||
try loadTemplate(at: boardURL)
|
||||
}
|
||||
|
||||
private func loadTemplate(at url: URL) throws -> BoardTemplate {
|
||||
switch TemplateEngine.load(templateAt: url, origin: .user) {
|
||||
case let .success(template): return template
|
||||
case let .failure(error): throw error
|
||||
}
|
||||
}
|
||||
|
||||
private func write(board url: URL, title: String, icon: String?, extraKeys: String) throws {
|
||||
let lane = url.appendingPathComponent("11111111-1111-4111-8111-111111111111", isDirectory: true)
|
||||
try FileManager.default.createDirectory(at: lane, withIntermediateDirectories: true)
|
||||
|
||||
var keys = ["schema: 1", "title: \(title)"]
|
||||
if let icon { keys.append("icon: \(icon)") }
|
||||
if !extraKeys.isEmpty { keys.append(extraKeys) }
|
||||
|
||||
try Data("---\n\(keys.joined(separator: "\n"))\n---\nBlurb.\n".utf8)
|
||||
.write(to: url.appendingPathComponent("index.md"))
|
||||
try Data("---\nschema: 1\ntitle: Lane\norder: 1024\n---\n".utf8)
|
||||
.write(to: lane.appendingPathComponent("index.md"))
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user