Documentation
¶
Overview ¶
Package workfile is nova-work's tree file: every issue of every repository of a source, with its full contents, as one restricted s-expression read by internal/worklang (docs/SPEC-WORK-V1.md section 1).
The package holds the model (Tree, Repo, Issue and what an issue carries), the canonical writer (Encode), the strict reader (Decode) and the field-for-field comparison (Diff). Encode then Decode is the identity on every Tree Encode accepts; Encode refuses a value it could not write back unchanged rather than writing it lossily. Nothing here reaches a network.
Index ¶
- Constants
- func Encode(t *Tree) ([]byte, error)
- func IssueURL(repo string, n int) string
- func Limits(maxBytes int) worklang.Limits
- func OriginOf(association string) string
- func Path(repo string, number int) string
- func Show(s string) string
- type Comment
- type Counts
- type Difference
- type Issue
- type LinkedPR
- type Milestone
- type Reference
- type Repo
- type Tree
Constants ¶
const Format = "v1"
Format is the tree file's format word, the second element of the top form.
const Web = "https://github.com/"
Web is the source's web root every repository and issue URL starts with.
Variables ¶
This section is empty.
Functions ¶
func Encode ¶
Encode writes the tree in its canonical form: repositories sorted by name, issues by number, labels and assignees sorted, every key of every record always written in one order, so one tree has exactly one file. It refuses what it could not read back unchanged: an enumeration outside [A-Z_], a repository or issue out of order or repeated, a number that is not positive. SPEC-WORK-V1 section 1.2 is the shape.
func Limits ¶
Limits is the reader's bounds for a tree file of at most maxBytes: the depth of the shape (section 1.2) with room to spare, and at most one atom per byte, so the byte bound is the one that binds.
func OriginOf ¶
OriginOf is the origin an author association gives: an issue filed by the owner, a member or a collaborator is internal, any other is external (SPEC-WORK-V1 section 1.4).
Types ¶
type Comment ¶
type Comment struct {
ID string
URL string
Author string
AuthorAssociation string
Created string
Updated string
Body string
}
Comment is one comment on an issue.
type Counts ¶
type Counts struct {
Repos, Issues, Comments, References, LinkedPRs int
}
Counts is the size of a tree.
type Difference ¶
type Difference struct {
Kind string // MISSING, EXTRA or DRIFT
Path string
Field string
Want string
Got string
}
Difference is one way a tree and a fresh fetch disagree, at one path: MISSING is on the source and not in the tree, EXTRA is in the tree and not on the source, DRIFT is a field whose value differs. Want is the source's value and Got the tree's, each rendered by Show.
func Diff ¶
func Diff(got, want *Tree, scope []string) []Difference
Diff compares the tree (got) with a fresh fetch (want), field for field, over the repositories named in scope (every repository of either when scope is empty). The result is sorted by path, then field; empty means the tree holds everything the source holds and nothing else.
func DiffIssue ¶
func DiffIssue(repo string, g, w *Issue) []Difference
DiffIssue compares every field of one issue, its comments by id, and its references and linked pull requests as sets of records.
type Issue ¶
type Issue struct {
Number int
URL string
NodeID string
Title string
State string
StateReason string
Origin string // internal or external (section 1.4)
Author string
AuthorAssociation string
Created string
Updated string
Closed string
Locked bool
LockReason string
Labels []string // sorted
Assignees []string // sorted
Milestone *Milestone
Body string
Comments []Comment // in creation order
References []Reference // cross-references to this issue, in timeline order
LinkedPRs []LinkedPR // pull requests that close it, in GitHub's order
}
Issue is one issue with its full contents. Enumerations (State, StateReason, AuthorAssociation, a comment's association, a linked pull request's state) keep GitHub's spelling (OPEN, NOT_PLANNED); the file writes them as keywords (:open, :not-planned). An empty string is GitHub's null.
type Reference ¶
type Reference struct {
Kind string
Repo string
Number int
URL string
Actor string
At string
WillClose bool
}
Reference is a cross-reference to the issue from an issue or a pull request: the source's kind (Issue or PullRequest), repository, number and URL, who made it and when, and whether the source will close the issue.
type Repo ¶
Repo is one repository: owner/name, its URL, whether it is archived, and every issue it holds, sorted by number.
type Tree ¶
type Tree struct {
Source string // "github"
Org string
Fetched string // RFC 3339, UTC
Repos []Repo
}
Tree is the root: the source it was imported from, the organization, the time the fetch began, and every repository imported, sorted by name.
func Decode ¶
Decode reads a tree file through internal/worklang (nothing is evaluated) and refuses, naming the path and the key, any record that is not exactly the shape Encode writes: a missing, repeated or unknown key, a value of the wrong kind, an issue whose URL is not the one its path gives. Every such problem of the file is named in the one error (SPEC-WORK-V1 section 1.2).
Source Files