workspace

Documentation

Overview

Package workspace merges what every repository in a workspace published into one id table and one reverse index (docs/SPEC.md §21), and reads the index layout that `publish` writes and `sync` reads:

repos/<name>/ledger.tsv    the repo's ledger at its published commit
repos/<name>/refs.tsv      its reverse index
repos/<name>/tests.tsv     optional; test outcomes for assert= (§9.2)
repos/<name>/blocks/<hash> optional; block bodies by content hash (§20.1),
                           so a consumer can classify a citation whose
                           acked hash is older than the published ledger

Everything here is pure over the bytes it is given; the CLI fetches the index, hands the files over, and writes what publish returns.

Index

• Constants
• Variables
• func BranchKey(repo, branch string) string
• func DecodeTests(r io.Reader) (map[string]check.TestOutcome, error)
• func EncodeTests(tests map[string]check.TestOutcome) []byte
• func MatchTests(defs []block.Block, byName map[string]check.TestOutcome) map[string]check.TestOutcome
• func ParseJUnit(r io.Reader) (map[string]check.TestOutcome, error)
• type Cite
• type Duplicate
• type Entry
  • func Read(fsys fs.FS) ([]Entry, error)
  • func (e Entry) BodyPath(hash string) string
  • func (e Entry) Dir() string
  • func (e Entry) Files() map[string][]byte
• type Merged
  • func Merge(entries []Entry) Merged
  • func MergeFor(entries []Entry, repos []string) Merged
  • func (m Merged) CheckDuplicate(repo string, l ledger.Ledger) error
  • func (m Merged) Others(repo string) ([]block.Block, []ledger.RefRow)
  • func (m Merged) Snapshot(repo string, cited map[Cite]bool, h ledger.Header) ledger.Foreign
  • func (m Merged) StaleAge(repo string, now time.Time) (time.Duration, error)
• type Published

Constants

const (
	ReposDir  = "repos"
	TestsFile = "tests.tsv"
	// BlocksDir holds published block bodies keyed by content hash. It is
	// content-addressed, so republishing an unchanged block writes nothing
	// and history accumulates without duplication.
	BlocksDir = "blocks"
)

Index layout.

const RepoKey = block.KeyRepo

RepoKey is the block arg under which a merged def carries its repository (block.KeyRepo). It is not a directive key an author writes; the merge adds it so a citation into another repo knows where the block lives.

Variables

var (
	ErrDuplicateAcrossRepos = errors.New("workspace: id defined in more than one repository")
	ErrNotPublished         = errors.New("workspace: repository has not published")
	ErrTestsFormat          = errors.New("workspace: tests.tsv format not understood")
)

Errors.

Functions

func BranchKey

func BranchKey(repo, branch string) string

BranchKey names one branch of one repository.

func DecodeTests

func DecodeTests(r io.Reader) (map[string]check.TestOutcome, error)

DecodeTests reads tests.tsv.

func EncodeTests

func EncodeTests(tests map[string]check.TestOutcome) []byte

EncodeTests renders test outcomes as TSV with a versioned header, sorted by id.

func MatchTests

func MatchTests(defs []block.Block, byName map[string]check.TestOutcome) map[string]check.TestOutcome

MatchTests maps JUnit outcomes onto defined test blocks by symbol: a def whose symbol is `TestSave` or `Suite.TestSave` takes the outcome of the testcase named `TestSave`. Defined tests with no result are recorded as skipped, which `assert=` treats as a failure (§9.2): a deleted or renamed test must not read as passing.

func ParseJUnit

func ParseJUnit(r io.Reader) (map[string]check.TestOutcome, error)

ParseJUnit reads a JUnit XML report (a `<testsuites>` root or a single `<testsuite>`) into outcomes keyed by test name.

Types

type Cite

type Cite struct{ ID, Branch string }

Cite is what a citation asks for from the index: an id, and the branch it selects with branch=, empty for the default branch. A snapshot records the defs cited this way and no others: taking every published branch of a cited id rewrote each downstream foreign.tsv whenever anyone published a branch, and stamped those rows with the default branch's commit.

type Duplicate

type Duplicate struct {
	ID    string   `json:"id"`
	Repos []string `json:"repos"`
}

Duplicate is an id published by more than one repository.

type Entry

type Entry struct {
	Repo string
	// Branch is empty for the default branch; a non-default branch
	// publishes under repos/<name>/@<branch>/ and its blocks carry
	// block.KeyBranch after the merge (Part VII "Ids and branches").
	Branch string
	Ledger ledger.Ledger
	Refs   ledger.Refs
	Tests  map[string]check.TestOutcome
	// Bodies are block bodies keyed by content hash (§20.1). Secret and
	// local blocks are excluded upstream, in System.Bodies, because the
	// index may be readable by people who cannot read the source repo.
	Bodies map[string]string
}

Entry is one repository's published state: what publish writes and what sync reads back.

func Read

func Read(fsys fs.FS) ([]Entry, error)

Read loads every published repo under an index tree. A repo directory with no ledger is skipped; a malformed file is an error naming it.

func (Entry) BodyPath

func (e Entry) BodyPath(hash string) string

BodyPath is where one block body lives, index-relative.

func (Entry) Dir

func (e Entry) Dir() string

Dir is the entry's directory inside the index.

func (Entry) Files

func (e Entry) Files() map[string][]byte

Files renders the entry as index-relative paths and contents: what `publish` writes for one repo.

type Merged

type Merged struct {
	// Defs are every published block, each carrying its repo in Args under
	// RepoKey, so a citing repo can build permalinks into the right place.
	Defs []block.Block
	// RepoOf maps an id to the repository that defines it.
	RepoOf map[string]string
	// Refs are the references each repository published from its default
	// branch, with the repo. A branch's are in BranchRefs: they carried no
	// branch marker, so an unmerged branch's citations were checked
	// upstream as the default branch's, and one doc line reported twice.
	Refs []ledger.RefRow
	// BranchRefs are references published from non-default branches, for a
	// question where erring towards "still cited" is the safe answer.
	BranchRefs []ledger.RefRow
	// Tests are the union of published test outcomes.
	Tests map[string]check.TestOutcome
	// Duplicates are rejected at publish (§21); a sync that still finds
	// them reports them so the offending publish can be fixed.
	Duplicates []Duplicate
	// Published records each repo's commit and scan time for staleness.
	Published map[string]Published
	// BranchPublished is Published for each non-default branch, keyed by
	// BranchKey, so a snapshot row taken from a branch records that
	// branch's commit rather than the default branch's.
	BranchPublished map[string]Published
	// Removed maps ids published by repositories that are no longer in the
	// workspace to that repo; MergeFor fills it, Merge leaves it empty.
	Removed map[string]string
}

Merged is the workspace view a check consumes.

func Merge

func Merge(entries []Entry) Merged

Merge combines entries. Entries are sorted by repo name first so the result is deterministic regardless of the order the index was read.

func MergeFor

func MergeFor(entries []Entry, repos []string) Merged

MergeFor merges only the repositories named (by their index name) and records every id the others had published, so a citing repo can say "repo removed" instead of "deleted" (§21). A nil list keeps every entry.

func (Merged) CheckDuplicate

func (m Merged) CheckDuplicate(repo string, l ledger.Ledger) error

CheckDuplicate reports whether publishing ledger for repo would define an id another repository already owns (§21 "duplicate ids across repos are rejected at publish").

func (Merged) Others

func (m Merged) Others(repo string) ([]block.Block, []ledger.RefRow)

Others returns the merged defs and refs that do not belong to repo: what a repo's own check should see in addition to its live scan.

func (Merged) Snapshot

func (m Merged) Snapshot(repo string, cited map[Cite]bool, h ledger.Header) ledger.Foreign

Snapshot builds the committed record of the foreign blocks `cited` names (§21). Only cited ids are included: the whole merged ledger would churn every downstream repo's `.ds/` on an unrelated upstream edit, which would teach people to ignore the diff that is the point of the file.

Each row carries the publishing repo's commit, so a later sync can say what moved and `status` can report how far behind a citation is.

func (Merged) StaleAge

func (m Merged) StaleAge(repo string, now time.Time) (time.Duration, error)

StaleAge reports how long ago a repo published, for the "index for api is N commits behind" style warning when commit distance is unknown.

type Published

type Published struct {
	Commit    string    `json:"commit"`
	ScannedAt time.Time `json:"scanned_at"`
}

Published is one repo's index stamp.