Reading

Purpose

Views a Source as the Draft it holds — the pure judgement of what a found document is. The name is the one the leading header declares; the Kind is the one the source's place gives it — the root descriptors first (a filename of "workspace.md", "lib.md", or "app.md" is a root wherever it sits, since they describe a stack or a layer rather than an artifact), then the kind folder (a "data", "projections", "contexts", or "ports" folder gives data, projection, context, or port). A document that is neither a root descriptor nor in a kind folder — a readme, a changelog, a note beside the tree — is not a specification, and the reading leaves it out; so is a document with no name header. The reading judges; it never repairs — a name is declared or the document is left out, never guessed from a filename.

Role Players

• source: Source — the found document to judge

Props

(none)

Role Methods

source

• declaredName: reads the source's leading header for the name it declares. Result: the declared name Text, if any
• givenKind: derives the Kind, if any, from the source's place — root when the filename is "workspace.md", "lib.md", or "app.md"; otherwise data, projection, context, or port when the folder is "data", "projections", "contexts", or "ports". Result: the Kind, if any

Functionalities

read

Judges the source: takes the declared name with declaredName and the kind with givenKind, and assembles the Draft — the source's layer, the kind, the name, and the text as found. When the source declares no name or its place gives no kind, there is no draft and the source is left out. Result: the Draft, if any

Scenarios

A data draft reads

Given: a Source at "convene" / "mix" / "data" / "Cell.md" whose text is the Cell draft — a leading header declaring "Cell" and a body speaking "Tumbler" When: read is performed Then: a Draft is yielded — layer "mix", kind "data", name "Cell", the text as found

A root descriptor reads as root wherever it sits

Given: a Source at "convene" / "mix" / "mix" / "lib.md" whose text is the layer's root descriptor — a leading header declaring "mix" and a body describing the transport domain When: read is performed Then: a Draft is yielded — layer "mix", kind "root", name "mix"

A note beside the tree is not a specification

Given: a Source at "convene" / "mix" / "mix" / "README.md" whose text has a leading header When: read is performed Then: no draft is yielded, because the place gives no kind

A document with no name header is left out

Given: a Source at "convene" / "mix" / "data" / "Cell.md" whose text begins with prose rather than a header When: read is performed Then: no draft is yielded, because no name is declared