Gate level detection on UUID folder-name shape
Only lowercase-hex 8-4-4-4-12 folder names are lane/card candidates; anything else is a stray — skipped with a distinct warning, never descended, never able to fail-fast a load. UUID-shaped folders keep the prior contract (missing index skips, malformed frontmatter fail-fasts). Design resolution from the Redesign board. +5 tests. Claude-Session: https://claude.ai/code/session_018BjQRYBR6jQja3jCRi5S3A
This commit is contained in:
@@ -47,6 +47,15 @@ private struct BoardFixture {
|
||||
}
|
||||
}
|
||||
|
||||
/// A fresh folder name with UUIDv4's shape (lowercase hex, `8-4-4-4-12`) — the only shape
|
||||
/// `BoardLoader` accepts as a lane/card candidate (01-storage-format.md § Fractal layout ▸
|
||||
/// Rules, "Name shape gates level detection"). Used wherever a test just needs *a* valid
|
||||
/// lane/card identity and doesn't care about the exact value; tests that need a specific
|
||||
/// lexicographic ordering use literal UUID-shaped strings instead.
|
||||
private func uuidFolderName() -> String {
|
||||
UUID().uuidString.lowercased()
|
||||
}
|
||||
|
||||
private func expectFailure(
|
||||
_ expectedReason: BoardLoadError.Reason,
|
||||
path: String,
|
||||
@@ -70,14 +79,20 @@ struct BoardLoaderWellFormedTests {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
try fixture.index("", "schema: 1\ntitle: Demo Board\ntemplate: {order: 3}\n")
|
||||
try fixture.index("b-lane", "schema: 1\norder: 2048\ntitle: B Lane\n")
|
||||
try fixture.index("a-lane", "schema: 1\norder: 1024\ntitle: A Lane\n")
|
||||
let laneA = uuidFolderName()
|
||||
let laneB = uuidFolderName()
|
||||
let cardFirst = uuidFolderName()
|
||||
let cardSecond = uuidFolderName()
|
||||
let cardDeleted = uuidFolderName()
|
||||
|
||||
try fixture.index("a-lane/card-2", "schema: 1\norder: 2048\ntitle: Second\n")
|
||||
try fixture.index("a-lane/card-1", "schema: 1\norder: 1024\ntitle: First\n")
|
||||
try fixture.index("", "schema: 1\ntitle: Demo Board\ntemplate: {order: 3}\n")
|
||||
try fixture.index(laneB, "schema: 1\norder: 2048\ntitle: B Lane\n")
|
||||
try fixture.index(laneA, "schema: 1\norder: 1024\ntitle: A Lane\n")
|
||||
|
||||
try fixture.index("\(laneA)/\(cardSecond)", "schema: 1\norder: 2048\ntitle: Second\n")
|
||||
try fixture.index("\(laneA)/\(cardFirst)", "schema: 1\norder: 1024\ntitle: First\n")
|
||||
try fixture.index(
|
||||
"a-lane/card-deleted",
|
||||
"\(laneA)/\(cardDeleted)",
|
||||
"schema: 1\norder: 512\ntitle: Gone\ndeleted: 2026-01-01T00:00:00Z\n"
|
||||
)
|
||||
|
||||
@@ -92,11 +107,11 @@ struct BoardLoaderWellFormedTests {
|
||||
Issue.record("expected template to be a mapping, got \(String(describing: model.template))")
|
||||
}
|
||||
|
||||
#expect(model.lanes.map(\.id.rawValue) == ["a-lane", "b-lane"])
|
||||
#expect(model.lanes.map(\.id.rawValue) == [laneA, laneB])
|
||||
|
||||
let laneA = try #require(model.lanes.first { $0.id.rawValue == "a-lane" })
|
||||
#expect(laneA.cards.map(\.id.rawValue) == ["card-deleted", "card-1", "card-2"])
|
||||
#expect(laneA.cards.map(\.isDeleted) == [true, false, false])
|
||||
let lane = try #require(model.lanes.first { $0.id.rawValue == laneA })
|
||||
#expect(lane.cards.map(\.id.rawValue) == [cardDeleted, cardFirst, cardSecond])
|
||||
#expect(lane.cards.map(\.isDeleted) == [true, false, false])
|
||||
#expect(result.warnings.isEmpty)
|
||||
}
|
||||
|
||||
@@ -107,86 +122,104 @@ struct BoardLoaderWellFormedTests {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
let lane = uuidFolderName()
|
||||
let card = uuidFolderName()
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index("lane-1", "schema: 1\norder: 1024\ndeleted: yesterday\n")
|
||||
try fixture.index("lane-1/card-1", "schema: 1\norder: 1024\ndeleted: yesterday\n")
|
||||
try fixture.index(lane, "schema: 1\norder: 1024\ndeleted: yesterday\n")
|
||||
try fixture.index("\(lane)/\(card)", "schema: 1\norder: 1024\ndeleted: yesterday\n")
|
||||
|
||||
let result = try BoardLoader.load(boardRoot: fixture.root)
|
||||
let lane = try #require(result.model.lanes.first { $0.id.rawValue == "lane-1" })
|
||||
#expect(lane.deleted == .malformed(raw: "yesterday"))
|
||||
#expect(lane.isDeleted)
|
||||
let loadedLane = try #require(result.model.lanes.first { $0.id.rawValue == lane })
|
||||
#expect(loadedLane.deleted == .malformed(raw: "yesterday"))
|
||||
#expect(loadedLane.isDeleted)
|
||||
|
||||
let card = try #require(lane.cards.first { $0.id.rawValue == "card-1" })
|
||||
#expect(card.deleted == .malformed(raw: "yesterday"))
|
||||
#expect(card.isDeleted)
|
||||
let loadedCard = try #require(loadedLane.cards.first { $0.id.rawValue == card })
|
||||
#expect(loadedCard.deleted == .malformed(raw: "yesterday"))
|
||||
#expect(loadedCard.isDeleted)
|
||||
}
|
||||
|
||||
@Test func tiesAreBrokenByFolderNameNotTitle() throws {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
// Both UUID-shaped so both are lane candidates; chosen so their lexicographic order
|
||||
// ('0' < 'f') is known ahead of time.
|
||||
let laneFirst = "00000000-0000-4000-8000-000000000000"
|
||||
let laneSecond = "ffffffff-ffff-4fff-8fff-ffffffffffff"
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
// Same order; titles are reversed relative to folder-name order, to catch a loader
|
||||
// that accidentally wires title into the tie-break instead of the folder name.
|
||||
try fixture.index("zzz-lane", "schema: 1\norder: 1024\ntitle: Should Be Second\n")
|
||||
try fixture.index("aaa-lane", "schema: 1\norder: 1024\ntitle: Should Be First\n")
|
||||
try fixture.index(laneSecond, "schema: 1\norder: 1024\ntitle: Should Be Second\n")
|
||||
try fixture.index(laneFirst, "schema: 1\norder: 1024\ntitle: Should Be First\n")
|
||||
|
||||
let model = try BoardLoader.load(boardRoot: fixture.root).model
|
||||
#expect(model.lanes.map(\.id.rawValue) == ["aaa-lane", "zzz-lane"])
|
||||
#expect(model.lanes.map(\.id.rawValue) == [laneFirst, laneSecond])
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Skip rules
|
||||
// MARK: - Skip rules (UUID-shaped candidates only)
|
||||
|
||||
struct BoardLoaderSkipTests {
|
||||
@Test func indexlessFolderBelowRootIsSkippedWithWarning() throws {
|
||||
@Test func indexlessUUIDFolderBelowRootIsSkippedWithMissingIndexWarning() throws {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
let lane = uuidFolderName()
|
||||
let orphanLane = uuidFolderName()
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index("lane-1", "schema: 1\norder: 1024\n")
|
||||
try fixture.emptyFolder("orphan-lane")
|
||||
try fixture.index(lane, "schema: 1\norder: 1024\n")
|
||||
try fixture.emptyFolder(orphanLane)
|
||||
|
||||
let result = try BoardLoader.load(boardRoot: fixture.root)
|
||||
#expect(result.model.lanes.map(\.id.rawValue) == ["lane-1"])
|
||||
#expect(result.warnings.contains(.missingIndex(path: "orphan-lane")))
|
||||
#expect(result.model.lanes.map(\.id.rawValue) == [lane])
|
||||
#expect(result.warnings.contains(.missingIndex(path: orphanLane)))
|
||||
}
|
||||
|
||||
@Test func indexlessCardFolderIsSkippedWithWarningAndRestOfBoardStillLoads() throws {
|
||||
@Test func indexlessUUIDCardFolderIsSkippedWithWarningAndRestOfBoardStillLoads() throws {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
let lane = uuidFolderName()
|
||||
let card = uuidFolderName()
|
||||
let orphanCard = uuidFolderName()
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index("lane-1", "schema: 1\norder: 1024\n")
|
||||
try fixture.index("lane-1/card-1", "schema: 1\norder: 1024\n")
|
||||
try fixture.emptyFolder("lane-1/orphan-card")
|
||||
try fixture.index(lane, "schema: 1\norder: 1024\n")
|
||||
try fixture.index("\(lane)/\(card)", "schema: 1\norder: 1024\n")
|
||||
try fixture.emptyFolder("\(lane)/\(orphanCard)")
|
||||
|
||||
let result = try BoardLoader.load(boardRoot: fixture.root)
|
||||
let lane = try #require(result.model.lanes.first)
|
||||
#expect(lane.cards.map(\.id.rawValue) == ["card-1"])
|
||||
#expect(result.warnings.contains(.missingIndex(path: "lane-1/orphan-card")))
|
||||
let loadedLane = try #require(result.model.lanes.first)
|
||||
#expect(loadedLane.cards.map(\.id.rawValue) == [card])
|
||||
#expect(result.warnings.contains(.missingIndex(path: "\(lane)/\(orphanCard)")))
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Strays ignored
|
||||
// MARK: - Strays ignored (non-directories, hidden entries, symlinks)
|
||||
|
||||
struct BoardLoaderStrayTests {
|
||||
@Test func strayFilesAndHiddenEntriesAreIgnoredWithoutWarning() throws {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
let lane = uuidFolderName()
|
||||
let card = uuidFolderName()
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index("lane-1", "schema: 1\norder: 1024\n")
|
||||
try fixture.index("lane-1/card-1", "schema: 1\norder: 1024\n")
|
||||
try fixture.index(lane, "schema: 1\norder: 1024\n")
|
||||
try fixture.index("\(lane)/\(card)", "schema: 1\norder: 1024\n")
|
||||
|
||||
try fixture.strayFile("notes.txt")
|
||||
try fixture.strayFile(".DS_Store")
|
||||
try fixture.strayFile("lane-1/notes.txt")
|
||||
try fixture.strayFile("\(lane)/notes.txt")
|
||||
_ = try fixture.emptyFolder(".git")
|
||||
|
||||
let result = try BoardLoader.load(boardRoot: fixture.root)
|
||||
#expect(result.model.lanes.map(\.id.rawValue) == ["lane-1"])
|
||||
#expect(result.model.lanes[0].cards.map(\.id.rawValue) == ["card-1"])
|
||||
#expect(result.model.lanes.map(\.id.rawValue) == [lane])
|
||||
#expect(result.model.lanes[0].cards.map(\.id.rawValue) == [card])
|
||||
#expect(result.warnings.isEmpty)
|
||||
}
|
||||
|
||||
@@ -194,15 +227,118 @@ struct BoardLoaderStrayTests {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
let realLane = uuidFolderName()
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
let realLane = try fixture.index("real-lane", "schema: 1\norder: 1024\n")
|
||||
let realLaneURL = try fixture.index(realLane, "schema: 1\norder: 1024\n")
|
||||
try FileManager.default.createSymbolicLink(
|
||||
at: fixture.root.appendingPathComponent("linked-lane"),
|
||||
withDestinationURL: realLane
|
||||
withDestinationURL: realLaneURL
|
||||
)
|
||||
|
||||
let result = try BoardLoader.load(boardRoot: fixture.root)
|
||||
#expect(result.model.lanes.map(\.id.rawValue) == ["real-lane"])
|
||||
#expect(result.model.lanes.map(\.id.rawValue) == [realLane])
|
||||
#expect(result.warnings.isEmpty)
|
||||
}
|
||||
}
|
||||
|
||||
// MARK: - Non-UUID-shaped folders are strays (01-storage-format.md § Fractal layout ▸ Rules,
|
||||
// "Name shape gates level detection")
|
||||
|
||||
struct BoardLoaderNonUUIDStrayTests {
|
||||
/// A non-UUID-shaped folder is a stray even when its `index.md` is perfectly valid
|
||||
/// lane-shaped content — the name shape gates candidacy before the file is ever read.
|
||||
@Test func nonUUIDFolderWithValidLaneShapedIndexIsIgnoredWithWarningAndBoardLoads() throws {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
let realLane = uuidFolderName()
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index(realLane, "schema: 1\norder: 1024\n")
|
||||
try fixture.index("todo", "schema: 1\norder: 2048\ntitle: Hand-authored lane\n")
|
||||
|
||||
let result = try BoardLoader.load(boardRoot: fixture.root)
|
||||
#expect(result.model.lanes.map(\.id.rawValue) == [realLane])
|
||||
#expect(result.warnings.contains(.nonUUIDFolderIgnored(path: "todo")))
|
||||
}
|
||||
|
||||
/// The motivating case: before this rule, a non-UUID folder with a broken `index.md`
|
||||
/// (missing required `order`) would fail-fast the whole load. Now the name shape gates it
|
||||
/// out as a stray before the loader ever parses the file, so the rest of the board still
|
||||
/// loads.
|
||||
@Test func nonUUIDFolderWithBrokenIndexIsIgnoredWithWarningAndBoardStillLoads() throws {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
let realLane = uuidFolderName()
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index(realLane, "schema: 1\norder: 1024\n")
|
||||
// Missing 'order' — would be a fail-fast .missingOrder if this were UUID-shaped.
|
||||
try fixture.index("todo", "schema: 1\ntitle: Broken hand-authored lane\n")
|
||||
|
||||
let result = try BoardLoader.load(boardRoot: fixture.root)
|
||||
#expect(result.model.lanes.map(\.id.rawValue) == [realLane])
|
||||
#expect(result.warnings.contains(.nonUUIDFolderIgnored(path: "todo")))
|
||||
}
|
||||
|
||||
/// Same motivating case, one level down: a non-UUID card-depth folder with a broken
|
||||
/// `index.md` is a stray, not a fail-fast, and doesn't stop its lane's other cards loading.
|
||||
@Test func nonUUIDCardFolderWithBrokenIndexIsIgnoredWithWarningAndLaneStillLoads() throws {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
let lane = uuidFolderName()
|
||||
let realCard = uuidFolderName()
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index(lane, "schema: 1\norder: 1024\n")
|
||||
try fixture.index("\(lane)/\(realCard)", "schema: 1\norder: 1024\n")
|
||||
try fixture.index("\(lane)/scratch", "schema: 1\n") // missing 'order' too
|
||||
|
||||
let result = try BoardLoader.load(boardRoot: fixture.root)
|
||||
let loadedLane = try #require(result.model.lanes.first)
|
||||
#expect(loadedLane.cards.map(\.id.rawValue) == [realCard])
|
||||
#expect(result.warnings.contains(.nonUUIDFolderIgnored(path: "\(lane)/scratch")))
|
||||
}
|
||||
|
||||
/// Case sensitivity: an uppercase (or mixed-case) UUID string doesn't have UUIDv4's
|
||||
/// *lowercase* shape, so it's a stray — folder names are never normalized.
|
||||
@Test func uppercaseUUIDFolderIsTreatedAsNonUUIDStray() throws {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
let realLane = uuidFolderName()
|
||||
let uppercaseLane = UUID().uuidString // Foundation renders this uppercase.
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index(realLane, "schema: 1\norder: 1024\n")
|
||||
try fixture.index(uppercaseLane, "schema: 1\norder: 2048\n")
|
||||
|
||||
let result = try BoardLoader.load(boardRoot: fixture.root)
|
||||
#expect(result.model.lanes.map(\.id.rawValue) == [realLane])
|
||||
#expect(result.warnings.contains(.nonUUIDFolderIgnored(path: uppercaseLane)))
|
||||
}
|
||||
|
||||
/// Reserved card children are covered "by construction" now: `attachments/` and
|
||||
/// `comments/` are non-UUID-shaped, and this loader never scans a card folder's contents
|
||||
/// anyway (cards are leaves) — either way, they must never surface a warning.
|
||||
@Test func reservedAttachmentsAndCommentsUnderCardProduceNoWarning() throws {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
let lane = uuidFolderName()
|
||||
let card = uuidFolderName()
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index(lane, "schema: 1\norder: 1024\n")
|
||||
try fixture.index("\(lane)/\(card)", "schema: 1\norder: 1024\n")
|
||||
try fixture.strayFile("\(lane)/\(card)/attachments/sketch.png")
|
||||
try fixture.strayFile("\(lane)/\(card)/comments/whatever.md")
|
||||
|
||||
let result = try BoardLoader.load(boardRoot: fixture.root)
|
||||
#expect(result.model.lanes.first?.cards.map(\.id.rawValue) == [card])
|
||||
#expect(result.warnings.isEmpty)
|
||||
}
|
||||
}
|
||||
@@ -320,39 +456,48 @@ struct BoardLoaderFailFastTests {
|
||||
}
|
||||
}
|
||||
|
||||
@Test func missingOrderOnLaneThrows() throws {
|
||||
/// A UUID-shaped folder still fails fast on structurally-bad content — the name shape only
|
||||
/// gates *candidacy*, never the validity of a folder that qualifies.
|
||||
@Test func missingOrderOnUUIDLaneThrows() throws {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index("lane-1", "schema: 1\n")
|
||||
let lane = uuidFolderName()
|
||||
|
||||
expectFailure(.missingOrder, path: "lane-1/index.md") {
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index(lane, "schema: 1\n")
|
||||
|
||||
expectFailure(.missingOrder, path: "\(lane)/index.md") {
|
||||
_ = try BoardLoader.load(boardRoot: fixture.root)
|
||||
}
|
||||
}
|
||||
|
||||
@Test func malformedOrderOnLaneThrows() throws {
|
||||
@Test func malformedOrderOnUUIDLaneThrows() throws {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index("lane-1", "schema: 1\norder: not-a-number\n")
|
||||
let lane = uuidFolderName()
|
||||
|
||||
expectFailure(.malformedOrder(raw: "not-a-number"), path: "lane-1/index.md") {
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index(lane, "schema: 1\norder: not-a-number\n")
|
||||
|
||||
expectFailure(.malformedOrder(raw: "not-a-number"), path: "\(lane)/index.md") {
|
||||
_ = try BoardLoader.load(boardRoot: fixture.root)
|
||||
}
|
||||
}
|
||||
|
||||
@Test func missingOrderOnCardThrows() throws {
|
||||
@Test func missingOrderOnUUIDCardThrows() throws {
|
||||
let fixture = try BoardFixture()
|
||||
defer { fixture.tearDown() }
|
||||
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index("lane-1", "schema: 1\norder: 1024\n")
|
||||
try fixture.index("lane-1/card-1", "schema: 1\n")
|
||||
let lane = uuidFolderName()
|
||||
let card = uuidFolderName()
|
||||
|
||||
expectFailure(.missingOrder, path: "lane-1/card-1/index.md") {
|
||||
try fixture.index("", "schema: 1\n")
|
||||
try fixture.index(lane, "schema: 1\norder: 1024\n")
|
||||
try fixture.index("\(lane)/\(card)", "schema: 1\n")
|
||||
|
||||
expectFailure(.missingOrder, path: "\(lane)/\(card)/index.md") {
|
||||
_ = try BoardLoader.load(boardRoot: fixture.root)
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user