site

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 12, 2026 License: MIT Imports: 44 Imported by: 0

Documentation

Overview

Package site is the home of the abcd site verb family (adr-47). It carries one thing today: the agreement test over the committed install surfaces.

Index

Constants

View Source 
const (
	CheckProvenance   = "provenance"
	CheckHero         = "hero"
	CheckBannedTokens = "banned-tokens"
	CheckSnippets     = "snippets"
	CheckBaseline     = "baseline"
	CheckMobile       = "mobile"
	CheckFigureLabels = "figure-labels"
)

The check names, as they appear in a finding and in the JSON envelope.

View Source 
const (
	AssetDarwinARM64 = "abcd-darwin-arm64"
	AssetDarwinAMD64 = "abcd-darwin-amd64"
	AssetLinuxARM64  = "abcd-linux-arm64"
	AssetLinuxAMD64  = "abcd-linux-amd64"
	// AssetChecksums is the manifest every install form verifies against, and
	// the one fixed-name asset the page links.
	AssetChecksums = "checksums.txt"
)

The released asset names the hero links directly, one per published platform.

The manifest's `release.assets` says these names come from the release workflow, and that claim is EARNED rather than asserted: the build does not parse the workflow (a page that reads CI configuration to decide what to link is a worse dependency than a constant), so `installsurface_test.go` holds this list to the exact `abcd-<os>-<arch>` matrix the four committed install surfaces derive. A platform added to the release matrix without a link here — or a link here to a platform nothing publishes — fails that test.

View Source 
const (
	LayoutCardsFromH2 = "cards-from-h2"
	LayoutLeadInCards = "lead-in-cards"
	LayoutProse       = "prose"
	LayoutInstall     = "install"
)

The layouts the composer implements. A manifest naming any other layout is refused at load rather than at render, so the failure names the manifest.

View Source 
const (
	EnvRender = "site-render"
	EnvDeploy = "site"
)

The two deployment environments the workflow runs in.

View Source 
const (
	// StatusChanged: something was written, locally or remotely.
	StatusChanged = "changed"
	// StatusNoChange: nothing was written, because every file, environment and
	// host was already current or is left to a remaining step (an existing
	// environment setup does not rewrite).
	StatusNoChange = "no_change"
	// StatusDeclined: a confirmation was declined, so a remote write did not
	// happen.
	StatusDeclined = "declined"
	// StatusRefused: a gate or a failure stopped a stage.
	StatusRefused = "refused"
)

Overall statuses.

View Source 
const (
	RemoteCurrent     = "current"
	RemoteWritten     = "written"
	RemoteDeclined    = "declined"
	RemoteRefused     = "refused"
	RemoteUnreachable = "unreachable"
	RemoteNotReached  = "not_reached"
	// RemoteUnrestricted: the environment exists and admits more than the
	// default branch and release tags. The forge's environment write replaces
	// an environment's whole protection set (its required reviewers and wait
	// timer with it), so setup never rewrites one that exists: restricting it
	// is a remaining step.
	RemoteUnrestricted = "unrestricted"
)

Remote outcome statuses (an environment).

View Source 
const (
	HostCurrent      = "current"
	HostWritten      = "written"
	HostDeclined     = "declined"
	HostRefused      = "refused"
	HostNoCredential = "no_credential"
	HostNotReached   = "not_reached"
)

Host outcome statuses.

View Source 
const AcknowledgementsRelPath = "ACKNOWLEDGEMENTS.md"

AcknowledgementsRelPath is the file whose numbering the page must agree with.

View Source 
const BaselineRelPath = ".abcd/site-baseline.json"

BaselineRelPath is the committed unresolved-reference ratchet.

View Source 
const CSLRelPath = ".abcd/development/research/references.csl.json"

CSLRelPath is where the record keeps its bibliography.

View Source 
const DefaultOutDir = "site"

DefaultOutDir is where the build writes when the caller names no directory.

View Source 
const DefaultProvider = "cloudflare"

DefaultProvider is the provider setup routes through when the manifest names none.

View Source 
const ManifestRelPath = ".abcd/site.json"

ManifestRelPath is the committed composition manifest.

View Source 
const SiteWorkflowRelPath = ".github/workflows/site.yml"

SiteWorkflowRelPath is the workflow setup writes.

Variables

View Source 
var CheckNames = []string{
	CheckProvenance, CheckHero, CheckBannedTokens, CheckSnippets,
	CheckBaseline, CheckMobile, CheckFigureLabels,
}

CheckNames is every check this verb runs, in the order it runs them.

View Source 
var ErrBaselineInvalid = errors.New("site: reference baseline is invalid")

ErrBaselineInvalid is returned for a baseline the build cannot read.

View Source 
var ErrManifestInvalid = errors.New("site: manifest is invalid")

ErrManifestInvalid is returned for a manifest the build cannot act on.

View Source 
var ErrNoManifest = errors.New("site: this repo declares no site composition (" + ManifestRelPath + " is absent)")

ErrNoManifest is returned when the repository declares no composition.

View Source 
var ErrNotManaged = errors.New("site setup: this is not a repository abcd manages (run `abcd ahoy install` first)")

ErrNotManaged refuses a folder abcd does not manage.

View Source 
var ErrUIInvalid = errors.New("site: interface strings are invalid")

ErrUIInvalid is returned for an unusable interface-string file.

View Source 
var LinkedBinaryAssets = []string{AssetDarwinARM64, AssetDarwinAMD64, AssetLinuxARM64, AssetLinuxAMD64}

LinkedBinaryAssets is the set of per-platform binaries the page offers.

View Source 
var PageNames = []string{"landing", "explorer", "record_pages", "graph", "timeline", "glossary", "status"}

PageNames is the closed page set, in the order the manifest documents it.

Functions

func CheckRecordBody added in v0.11.1 

func CheckRecordBody(rel, content string) error

CheckRecordBody reports the construct a record's body carries that the site renderer refuses, or nil when the body renders. It runs the same sections and the same block renderer a record page is built with; only the link rewrite and the image assets are neutral, because a record is checked here for its markdown, not for where its links land. It exists so the record gate can refuse, in the change that writes it, a body the site render would refuse at the far end of preflight (iss-2608301350287219).

func CredentialNames added in v0.12.0 

func CredentialNames() []string

CredentialNames are the credentials the site setup reads, one per hosting provider.

func CredentialService added in v0.12.0 

func CredentialService(name string, adapter hosting.Adapter) (credential.Service, bool)

CredentialService is the walkthrough's service for name when adapter reads it: false for a name the site setup does not read.

func CredentialServiceFor added in v0.12.0 

func CredentialServiceFor(name string) (credential.Service, bool)

CredentialServiceFor is CredentialService over every hosting provider the site setup knows.

func HeadCommit 

func HeadCommit(repoRoot string) string

HeadCommit is the short SHA at HEAD, or "" outside a repository. The footer prints it, so a build from a detached tree still says which bytes it read.

func LinkDefinitions 

func LinkDefinitions(md string) map[string]string

LinkDefinitions collects a document's link reference definitions.

func LoadPrinciples 

func LoadPrinciples(repoRoot, dir string) ([]lint.RecordNode, error)

LoadPrinciples reads the principle store as record nodes.

An absent directory is a state, not a fault: it yields no nodes and no error, and the foundations page is omitted rather than rendered empty.

func PrinciplesDir 

func PrinciplesDir(cfg lint.Config) string

PrinciplesDir is the record's principle store, or "" where the lint configuration names no record root.

func Providers added in v0.11.1 

func Providers() []string

Providers is the adapter list, by name, in the order abcd ships them.

func RecordRoute 

func RecordRoute(n ExportNode) string

RecordRoute is where one record's page is served from.

func StripFrontmatter 

func StripFrontmatter(t string) (string, int)

StripFrontmatter removes a leading YAML frontmatter block and reports how many lines it consumed, so a caller can keep reporting source lines against the original file. It is the script's `strip_frontmatter`: a document that does not open with `---`, or whose frontmatter never closes, is returned untouched.

Blank lines and complete HTML comments AHEAD of the opening `---` are skipped with it. A record file may carry an attribution comment above its frontmatter — every glossary term file does, from the template it was adapted from — and a stripper that recognised frontmatter only at byte zero published the whole block as prose: the fields arrived on the page as a heading nobody wrote. The three record readers that already tolerate that comment (`lint`, `glossary` and this) now agree about where a file's frontmatter begins.

func StripMarks added in v0.14.0 

func StripMarks(t string) string

StripMarks drops the emphasis and code marks a heading's anchor ignores, the first step of slug and nothing more: punctuation and spacing are left as they render. It is exported for a caller asking whether two headings READ the same, a finer question than whether they share an anchor.

Types

type Arrangements 

type Arrangements struct {
	// Coil places every record in date order, winding outward.
	Coil []Point `json:"coil"`
	// Links places connected work in islands and everything else on the rim.
	Links []Point `json:"links"`
	// Degree is each record's weighted connectedness; Radius its bubble size in
	// reference pixels.
	Degree []float64 `json:"degree"`
	Radius []float64 `json:"radius"`
	// Order is the coil's placement order.
	Order []int `json:"order"`
	// Months marks where each month begins along the coil.
	Months []MonthMark `json:"months"`
	// Overlaps is the packing's own sanity check: the number of bubble pairs
	// that intersect, summed over BOTH arrangements. It must be zero, and it is
	// published so a reader can see that it is rather than take the claim on
	// trust.
	Overlaps int `json:"overlaps"`
	// CoilRadius is the packed radius before normalisation to the unit disk.
	CoilRadius float64 `json:"coil_radius"`
	// RefScale is the scale the radii are quoted at.
	RefScale float64 `json:"ref_scale"`
	// Isolated counts records with no link of any kind.
	Isolated int `json:"isolated"`
	// Islands are the sizes of the connected groups of three or more; Pairs and
	// Unlinked the counts of the two smaller shapes.
	Islands  []int `json:"islands"`
	Pairs    int   `json:"pairs"`
	Unlinked int   `json:"unlinked"`
	// DateRange is the first and last effective date placed — when the records
	// were WRITTEN.
	DateRange [2]string `json:"date_range"`
	// Span is DateRange extended to the last day any placed record's file was
	// touched, which is the axis a timeline draws: a decision written in May and
	// amended in August occupies both ends of it, and a range that stopped at the
	// writing dates would cut the chart short of its own newest fact.
	Span [2]string `json:"span"`
}

Arrangements holds both precomputed layouts plus the numbers that describe them, one entry per node in the caller's own order.

func ComputeArrangements 

func ComputeArrangements(nodes []LayoutNode, typed, mentions [][2]int) Arrangements

ComputeArrangements places every record twice: once in date order along the coil, once by its typed links. typed and mentions are index pairs into nodes; mentions are excluded from the link arrangement (with them it is a hairball) but do count toward a bubble's size.

type Asker added in v0.11.1 

type Asker interface {
	Confirm(question string) bool
}

Asker confirms a remote write. A nil Asker declines.

type Author 

type Author struct {
	Name    string `json:"name"`
	Commits int    `json:"commits"`
	// Profile is the author's forge profile URL, derived only from a forge
	// noreply address — which carries no real mailbox, only the public
	// username — so exporting it republishes nothing the rule above protects.
	// An author whose address is not a noreply simply has none.
	Profile string `json:"profile,omitempty"`
	// contains filtered or unexported fields
}

Author is one authorship line.

The address is deliberately absent. `git shortlog -sne` yields it and the mailmap folds it, so it is read — but the site is published, and republishing a contributor's address on a web page is a harvesting surface the record never asked for. The name is the attribution; the address stays in git.

type Authorship 

type Authorship struct {
	// Commits is the total number of commits in the history walked.
	Commits int `json:"commits"`
	// Authored is Commits less the merges: the commits a person actually wrote,
	// and the only honest denominator for a disclosure rate.
	Authored int `json:"authored"`
	// Merges is what was set aside to get there. It is published rather than
	// quietly subtracted, because a denominator that changed without saying so
	// is how the rate went wrong in the first place.
	Merges int `json:"merges"`
	// Humans are the authors of record, mailmap-folded, most commits first.
	Humans []Author `json:"humans"`
	// Bots are the forge bots and tool-authored commits, kept in a separate row
	// so a reader never has to guess which lines are people.
	Bots []Author `json:"bots"`
	// AssistedCommits is how many AUTHORED commits declare assistance — the
	// commit-level count, and the numerator of the disclosure rate.
	AssistedCommits int `json:"assisted_commits"`
	// Assisted is the number of `Assisted-by:` trailer occurrences that NAME A
	// MODEL, across authored commits. It is what the per-model tally sums to —
	// it is rendered as the chart's own total, so it can be nothing else; it is
	// not a number of commits, and a commit naming two models counts twice here
	// and once in AssistedCommits. Rendering this one as a count of commits is
	// the defect that published a disclosure rate well below the truth.
	//
	// A declaration that names no model (see chartableModel) is counted in
	// AssistedCommits and not here, so this can sit below that figure. The
	// disclosure rate is computed from the commit-level counts and is unaffected.
	Assisted int `json:"assisted"`
	// MultiTrailerCommits is how many AUTHORED commits declare more than one
	// model. It is counted per COMMIT rather than derived as Assisted minus
	// AssistedCommits: that subtraction is a surplus of occurrences, and a
	// single commit naming three models would report two — publishing an
	// occurrence figure under a label that says commits, which is the exact
	// conflation this type exists to keep apart.
	MultiTrailerCommits int `json:"multi_trailer_commits"`
	// DeclaredNone is the number of AUTHORED commits declaring
	// `Assisted-by: None` — work no tool touched, saying so.
	DeclaredNone int `json:"declared_none"`
	// ComposedByAbcd is the number of AUTHORED commits declaring
	// `Assisted-by: abcd:<version>` and no model: text abcd composed from record
	// facts (ruling PC1), which no model wrote and which a tool did touch. It is
	// neither assistance nor a declaration of none, so it is counted in neither
	// and never charted, and it is stated beside DeclaredNone. A commit naming a
	// model as well is assisted: a model's text is in it.
	ComposedByAbcd int `json:"composed_by_abcd"`
	// Undeclared is the number of AUTHORED commits carrying no trailer at all.
	// It is published because an absent trailer and a forgotten one are the
	// same bytes, and the honest number is the one that says how much of the
	// history predates the convention. Merges are excluded: nobody wrote them,
	// so nothing was forgotten.
	Undeclared int `json:"undeclared"`
	// ByModel tallies each distinct declared MODEL by OCCURRENCE, most first —
	// the trailer-shaped values alone, clipped to the grammar.
	ByModel []ModelTally `json:"by_model"`
}

Authorship is the whole picture: who authored, what assisted, the commits abcd composed, and the commits that declared no assistance at all.

func LoadAuthorship 

func LoadAuthorship(repoRoot string) (Authorship, error)

LoadAuthorship reads the authorship facts out of git. A directory that is not a repository yields a zero Authorship and no error.

type Baseline 

type Baseline struct {
	SchemaVersion        int             `json:"schema_version"`
	UnresolvedReferences []BaselineEntry `json:"unresolved_references"`
}

Baseline is `.abcd/site-baseline.json`.

func LoadBaseline 

func LoadBaseline(repoRoot, rel string) (Baseline, bool, error)

LoadBaseline reads the ratchet at rel, or at the default path when rel is empty.

The distinction between "named" and "defaulted" is the whole point. A repository that declares no baseline simply has none, and the build carries on (found=false). A repository that NAMES one in its manifest and does not carry it is a different situation: the ratchet it thinks it armed is not being measured against anything, and reporting a count of zero would read as good news. That refuses.

type BaselineEntry 

type BaselineEntry struct {
	From string `json:"from"`
	To   string `json:"to"`
}

BaselineEntry is one reference the baseline admits.

type Bibliography 

type Bibliography struct {
	// Entries are the sources, in the file's own order — which is the order
	// their numbers are cited in.
	Entries []CSLEntry
	// Path is the CSL file the entries came from.
	Path string
	// Inspirations are the acknowledgement file's credited ideas, as markdown
	// list items, and Heading its own heading for them.
	Inspirations     []Block
	InspirationsLead []Block
	Heading          string
	RefsHeading      string
	// Source is the acknowledgement file, RefsAnchor and InspAnchor the headings
	// the numbered sources and the credited ideas sit under, and AckLinkDefs its
	// link reference definitions — so every block rendered from that file can
	// carry the span it came from.
	Source      string
	RefsAnchor  string
	InspAnchor  string
	AckLinkDefs map[string]string
}

Bibliography is the rendered bibliography plus the credited inspirations beside it.

func LoadBibliography 

func LoadBibliography(repoRoot, cslRel, ackRel string) (*Bibliography, error)

LoadBibliography reads the CSL file and the acknowledgement file, checks that they number the same sources the same way, and returns what the page renders.

An ABSENT CSL file is a state, not a fault: the page and its navigation entry are omitted and the build succeeds. A PRESENT file whose numbering disagrees with the acknowledgement list is a fault, and it fails the build naming the entry — the citations in the record's prose are numbers, and a number pointing at the wrong source is worse than no page at all.

type Block 

type Block = mdrender.Block

Block is one top-level markdown block.

func Blocks 

func Blocks(md string, start int) []Block

Blocks splits a section body into its top-level blocks.

type BlockRef 

type BlockRef struct {
	File    string `json:"file"`
	Heading string `json:"heading"`
}

BlockRef selects a span of a file by heading.

type BranchPolicy added in v0.11.1 

type BranchPolicy struct {
	Name string `json:"name"`
	Type string `json:"type"`
}

BranchPolicy is one deployment policy: a branch or tag name pattern.

type BuildStamp 

type BuildStamp struct {
	Version     string `json:"version"`
	Commit      string `json:"commit"`
	GeneratedAt string `json:"generated_at"`
	// Preview marks a build of an untagged tree — main, typically, rendered to a
	// preview deployment. Such a build has no version, and saying so is the point
	// of the field: with the version falling back to the newest CHANGELOG
	// heading, a preview would otherwise stamp itself with a release it is not,
	// and a reader could go and verify that release against a different tree.
	//
	// The version field stays PRESENT and empty on a preview rather than being
	// omitted. A reader of the export, and a test comparing two builds, both get
	// one shape to think about instead of two, and "version": "" beside
	// "preview": true says the absence is deliberate — where a missing key looks
	// like an older export or a dropped field.
	Preview bool `json:"preview,omitempty"`
}

BuildStamp is what produced this file. Every field is injected by the caller so a test can pin the whole export byte for byte.

type CSLEntry 

type CSLEntry struct {
	ID             string     `json:"id"`
	Type           string     `json:"type"`
	Author         []CSLName  `json:"author"`
	Title          string     `json:"title"`
	ContainerTitle string     `json:"container-title"`
	Volume         string     `json:"volume"`
	Issue          string     `json:"issue"`
	Page           string     `json:"page"`
	Publisher      string     `json:"publisher"`
	PublisherPlace string     `json:"publisher-place"`
	Issued         *CSLIssued `json:"issued"`
	DOI            string     `json:"DOI"`
	URL            string     `json:"URL"`
}

CSLEntry is one bibliography record, in the CSL-JSON fields the record uses.

func (CSLEntry) Render 

func (e CSLEntry) Render() string

Render formats one entry as HTML: authors, year, title, container, the publication details the type carries, and the DOI or URL as a link.

type CSLIssued 

type CSLIssued struct {
	DateParts [][]json.Number `json:"date-parts"`
}

CSLIssued is a CSL date, of which only the year is used.

func (*CSLIssued) Year 

func (d *CSLIssued) Year() string

Year is the entry's year, or "" where it carries none.

type CSLName 

type CSLName struct {
	Family  string `json:"family"`
	Given   string `json:"given"`
	Literal string `json:"literal"`
}

CSLName is one author.

type Chapter 

type Chapter struct {
	Letter  string   `json:"letter"`
	Page    string   `json:"page"`
	Layout  string   `json:"layout"`
	Feature *Feature `json:"feature,omitempty"`
	// Icons declares how a card gets its picture: an image on its own line
	// before a bold lead-in paragraph is that card's icon.
	Icons string `json:"icons,omitempty"`
	// TablePortraits names the chapter whose sections supply the portraits that
	// sit above this chapter's table column labels.
	TablePortraits string  `json:"table_portraits,omitempty"`
	Figure         *Figure `json:"figure,omitempty"`
	Lead           string  `json:"lead,omitempty"`
	// Release names where the chapter's release links read from. The build reads
	// `from` (the changelog) and links the released asset names, which the
	// committed install-surface agreement test holds to `assets`.
	Release *Release `json:"release,omitempty"`
	After   string   `json:"after,omitempty"`
	// Tabs describes the arrangement the install layout builds.
	Tabs string   `json:"tabs,omitempty"`
	Left []string `json:"left,omitempty"`
}

Chapter is one lettered section of the landing page.

type CheckFinding 

type CheckFinding struct {
	Check string `json:"check"`
	// Where is the emitted file, or the repository file, the finding is about.
	Where string `json:"where"`
	// Source is the `data-src` span the offending content came from, where the
	// finding is about composed content.
	Source string `json:"source,omitempty"`
	// Detail says what is wrong, in the reader's terms.
	Detail string `json:"detail"`
}

CheckFinding is one failure. Every finding names the check that raised it and the place a reader's next edit goes.

type CheckRequest 

type CheckRequest struct {
	// RepoRoot is the repository the output was rendered from.
	RepoRoot string
	// OutDir is the built output directory, absolute or relative to the caller.
	OutDir string
	// Lanes is the state-file reader a build the check makes hands the Status
	// page, as Request.Lanes; nil reads as an absent state file.
	Lanes statusblock.LaneReader
}

CheckRequest is one run of the gates.

type CheckResult 

type CheckResult struct {
	OutDir string `json:"out_dir"`
	// Pages are the emitted HTML files read, output-relative and sorted.
	Pages []string `json:"pages"`
	// Composed are the subset held to the composed-surface rules.
	Composed []string `json:"composed"`
	// Checks are the gates that ran.
	Checks []string `json:"checks"`
	// Findings fail the run.
	Findings []CheckFinding `json:"findings"`
	// Notes do not. The ratchet's shrink invitation is the only one: a baseline
	// entry whose reference has been fixed is news, not a failure.
	Notes []CheckFinding `json:"notes"`
	// Built reports whether this run rendered the output itself.
	Built bool `json:"built"`
}

CheckResult is what one run found.

func Check 

func Check(req CheckRequest) (CheckResult, error)

Check runs every gate against an already-built output directory.

An output directory with no `index.html` is BUILT first rather than refused: the check is about what the repository publishes, and a caller who has not rendered yet is asking the same question as one who has.

func (CheckResult) OK 

func (r CheckResult) OK() bool

OK reports whether the run found nothing that fails it.

type Contributors 

type Contributors struct {
	Policy PolicyRef `json:"policy"`
}

Contributors names the attribution policy span the contributors page quotes.

type ContributorsUI 

type ContributorsUI struct {
	Authors  string `json:"authors"`
	Tools    string `json:"tools"`
	Assisted string `json:"assisted"`
	Trailers string `json:"trailers"`
	// MergesExcluded names what the disclosure rate leaves out, so the
	// denominator is never a silent choice.
	MergesExcluded string `json:"merges_excluded"`
	// DeclaredNone, ComposedByAbcd and Undeclared label the three commit-level
	// facts stated beneath the occurrence chart rather than drawn inside it.
	DeclaredNone   string `json:"declared_none"`
	ComposedByAbcd string `json:"composed_by_abcd"`
	Undeclared     string `json:"undeclared"`
}

ContributorsUI labels the attribution page.

type Counts 

type Counts struct {
	ByType      map[string]int            `json:"by_type"`
	ByLifecycle map[string]map[string]int `json:"by_lifecycle"`
	ByStatus    map[string]map[string]int `json:"by_status"`
}

Counts is the corpus by store, by lifecycle bucket, and by declared status.

The last of those is not a duplicate of the second. A store that grades its records by MOVING them between directories (intents, specs, issues) is counted by lifecycle; a FLAT store that grades them with a frontmatter field (decisions) has one empty lifecycle bucket and its whole shape in the status field. A page that only read the lifecycle would show a flat store as a single undifferentiated block.

type DocsRefs 

type DocsRefs struct {
	Index string `json:"index"`
	CLI   string `json:"cli"`
}

DocsRefs names the documentation pages the site links its docs surface to.

type EnvironmentOutcome added in v0.11.1 

type EnvironmentOutcome struct {
	Name    string   `json:"name"`
	Status  string   `json:"status"`
	Changes []string `json:"changes,omitempty"`
}

EnvironmentOutcome is one environment's result.

type EnvironmentState added in v0.11.1 

type EnvironmentState struct {
	ProtectedBranches    bool
	CustomBranchPolicies bool
}

EnvironmentState is one environment's deployment policy as the forge reports it. An environment with no policy at all admits every ref.

type ExportEdge 

type ExportEdge struct {
	From string `json:"from"`
	To   string `json:"to"`
	Rel  string `json:"rel"`
}

ExportEdge is one distinct typed link.

type ExportMention 

type ExportMention struct {
	From string `json:"from"`
	To   string `json:"to"`
}

ExportMention is one undirected body reference.

type ExportNode 

type ExportNode struct {
	ID        string `json:"id"`
	Type      string `json:"type"`
	Lifecycle string `json:"lifecycle"`
	Title     string `json:"title"`
	Path      string `json:"path"`
	Status    string `json:"status,omitempty"`
	Kind      string `json:"kind,omitempty"`
	Severity  string `json:"severity,omitempty"`
	// Date is the record's effective date: its own frontmatter date where it
	// carries one, else the day its file first appeared in git.
	Date string `json:"date"`
	// Derived is true for a record that declares NO frontmatter — its id is its
	// file name, its title its first heading, its dates git's. A page must not
	// present those as fields the record stated, and a chart must not read a
	// lifecycle it never had.
	Derived bool `json:"derived,omitempty"`
	// Dates are the file's three git dates.
	Dates FileDates `json:"dates"`
	// Degree is the weighted connectedness the chart sizes bubbles by.
	Degree float64 `json:"degree"`
}

ExportNode is one record.

type Feature 

type Feature struct {
	Kind  string   `json:"kind"`
	Pick  string   `json:"pick"`
	Parts []string `json:"parts"`
}

Feature declares the quoted record block a chapter closes with.

func (*Feature) FeatureWants 

func (f *Feature) FeatureWants(part string) bool

FeatureWants reports whether a chapter's feature block quotes the named part.

type Figure 

type Figure struct {
	Kind string `json:"kind"`
	// LabelsFromPage asks that every label in the figure be a phrase on the page
	// it illustrates, so a diagram cannot drift from the prose beside it.
	// CONSUMED by `abcd lint site`'s loop-figure gate (spc-37, ported from the
	// script's closing check). Validated here too — it is meaningless without a
	// figure to check — so a manifest that asks for it and names no figure is
	// refused at load rather than at render.
	LabelsFromPage bool `json:"labels-from-page,omitempty"`
}

Figure declares a chapter's lifted illustration.

type FileDates 

type FileDates struct {
	// Created is the day the file first appeared, under any path.
	Created string `json:"created"`
	// Entered is the day it arrived in the directory it occupies now. For a
	// file that never moved, it equals Created.
	Entered string `json:"entered"`
	// Touched is the day the last commit changed it.
	Touched string `json:"touched"`
}

FileDates is one file's biography, each date as YYYY-MM-DD.

type Forge added in v0.11.1 

type Forge interface {
	// Repo names the repository every call acts on.
	Repo() string
	// DefaultBranch reads the repository's default branch: the branch the
	// workflow gates on and the environments admit.
	DefaultBranch(ctx context.Context) (string, error)
	// Environments reads every environment the repository has, by name.
	Environments(ctx context.Context) (map[string]EnvironmentState, error)
	// Policies reads one environment's deployment branch and tag policies.
	Policies(ctx context.Context, env string) ([]BranchPolicy, error)
	// PutEnvironment creates env restricted to custom policies. The forge's
	// write replaces an environment's whole protection set, so setup calls it
	// only for an environment that does not exist.
	PutEnvironment(ctx context.Context, env string) error
	// AddPolicy admits one branch or tag pattern to env.
	AddPolicy(ctx context.Context, env string, p BranchPolicy) error
	// SecretNames lists the names of env's secrets. Values are never read.
	SecretNames(ctx context.Context, env string) ([]string, error)
}

Forge is the slice of the forge `abcd site setup` reads and writes: the deployment environments the site workflow runs in, and the NAMES of the secrets one of them holds. It never reads or writes a secret's value — the forge encrypts those, and setting one is the person's step.

func GitHubForge added in v0.11.1 

func GitHubForge(dir string) (Forge, error)

GitHubForge is the forge for the checkout at dir, or an error saying why the checkout names no GitHub repository abcd may act on.

type GraphUI 

type GraphUI struct {
	Arrange        string `json:"arrange"`
	ByDate         string `json:"by_date"`
	ByLinks        string `json:"by_links"`
	Filters        string `json:"filters"`
	Find           string `json:"find"`
	Mentions       string `json:"mentions"`
	BrowseList     string `json:"browse_list"`
	ZoomIn         string `json:"zoom_in"`
	ZoomOut        string `json:"zoom_out"`
	ResetView      string `json:"reset_view"`
	FullScreen     string `json:"full_screen"`
	ExitFullScreen string `json:"exit_full_screen"`
	Close          string `json:"close"`
	Back           string `json:"back"`
	Forward        string `json:"forward"`
	History        string `json:"history"`
	Linked         string `json:"linked"`
	NoLinks        string `json:"no_links"`
}

GraphUI labels the relationship chart's controls.

type Health 

type Health struct {
	// Unresolved names every typed reference the record cannot account for.
	Unresolved []ExportEdge `json:"unresolved"`
	// Retired are ids a record declares it pruned; a reference naming one
	// resolves to that declaration rather than to a file, so it is not
	// unresolved.
	Retired []string `json:"retired"`
	// BaselineCount is the committed ratchet's size, where the repository keeps
	// one. The ratchet itself is a check, not an export.
	BaselineCount int `json:"baseline_count"`
}

Health is the record's reference hygiene as measured, not as claimed.

type HealthUI 

type HealthUI struct {
	// Unresolved is a typed reference whose target no file answers to.
	Unresolved string `json:"unresolved"`
	// Isolated is a record nothing links to and which links to nothing.
	Isolated string `json:"isolated"`
	// SameAuthor is a candidate duplicate identity: two author names that the
	// mailmap has not folded but which the evidence says are one person.
	SameAuthor string `json:"same_author"`
	// Undeclared is an authored commit carrying no `Assisted-by:` trailer.
	Undeclared string `json:"undeclared"`
	// MultiTrailer is a commit declaring more than one assisting model — not a
	// fault, but the reason a trailer tally and a commit count differ.
	MultiTrailer string `json:"multi_trailer"`
	// NotADefect is what the multi-trailer panel says about itself. The family
	// is the one on the page that reports no fault at all, and a panel sitting
	// among findings without saying so is read as a fifth finding.
	NotADefect string `json:"not_a_defect"`
	// SupersedesLead says what a supersession row means, and that the family
	// reports no fault: the left record replaced the right one.
	SupersedesLead string `json:"supersedes_lead"`
	// Clean is what the page says when a family has nothing to report.
	Clean string `json:"clean"`
	// Suggestion prefixes the line a finding proposes a human confirm.
	Suggestion string `json:"suggestion"`
}

HealthUI labels the health page's finding families. Every one of them is a check the record can be run against ITSELF — nothing here is a judgement, an opinion, or a number a human has to interpret before acting on it.

type Hero 

type Hero struct {
	Page   string `json:"page"`
	Figure string `json:"figure"`
}

Hero names the page the headline, lede and figure come from.

type History 

type History struct {
	// Files maps a repo-relative path (as of HEAD) to its dates.
	Files map[string]FileDates
	// First is the day of the oldest commit; Last the day of the newest.
	First string
	Last  string
	// Commits is the number of commits the walk saw.
	Commits int
}

History is the result of the one pass.

func LoadHistory 

func LoadHistory(repoRoot string) (History, error)

LoadHistory replays the repository's history and returns every live file's dates. A directory that is not a git repository yields an empty history and no error: an unversioned tree is a state the site renders around, not a fault.

func (History) EffectiveDate 

func (h History) EffectiveDate(path, frontmatterDate string) string

EffectiveDate is the date a record is placed by: the date it declares in its own frontmatter where it carries one, else the day its file first appeared. It is the ordering key of both chart arrangements, so it lives here with the history rather than being re-derived per consumer.

func (History) EnteredBucket 

func (h History) EnteredBucket(path string) string

EnteredBucket is the day a record arrived in the lifecycle directory it sits in now — for a shipped intent, the day it shipped. It is the same fact as FileDates.Entered, named for the question the site actually asks of it.

type HistoryMeta 

type HistoryMeta struct {
	FirstCommit string `json:"first_commit"`
	LastCommit  string `json:"last_commit"`
	Commits     int    `json:"commits"`
}

HistoryMeta summarises the git walk.

type Home 

type Home struct {
	Hero     Hero      `json:"hero"`
	Chapters []Chapter `json:"chapters"`
}

Home is the landing page's composition.

type HostOutcome added in v0.11.1 

type HostOutcome struct {
	Provider string `json:"provider"`
	Name     string `json:"name"`
	Domain   string `json:"domain,omitempty"`
	// Credential is the name of the credential the stage resolved, never
	// its value (itd-2609221017023290 criterion 5).
	Credential string   `json:"credential"`
	Status     string   `json:"status"`
	Changes    []string `json:"changes,omitempty"`
	Address    string   `json:"address,omitempty"`
	Detail     string   `json:"detail,omitempty"`
}

HostOutcome is the host stage's result.

type Hosting added in v0.11.1 

type Hosting struct {
	Provider string `json:"provider"`
	Name     string `json:"name"`
	Domain   string `json:"domain,omitempty"`
}

Hosting is the manifest's `hosting` block: which provider adapter `abcd site setup` routes the site through, the name of the host it creates there, and the custom domain it attaches, if any. It holds no credential and no account identifier: the credential is the machine's, read by name at setup time, and never enters the repository.

type LabelsAddedError added in v0.13.0 

type LabelsAddedError struct {
	File   string
	Labels []string
	Err    error
}

LabelsAddedError is a build that failed after it added missing interface labels to the repository's ui.json (the TG1 ruling): the write stands, so the error names the file and each label added, and unwraps to the failure.

func (*LabelsAddedError) Error added in v0.13.0 

func (e *LabelsAddedError) Error() string

func (*LabelsAddedError) Unwrap added in v0.13.0 

func (e *LabelsAddedError) Unwrap() error

type LayoutNode 

type LayoutNode struct {
	// Type is the record's store name; it sets the bubble's size class and the
	// same-day tie-break.
	Type string
	// Date is the effective date the record is placed by.
	Date string
	// Num is the id number, the last tie-break.
	Num int
	// Touched is the day the record's file last changed. It places nothing — the
	// arrangements are chronological by when a record was WRITTEN — but it is
	// what the span a timeline draws has to reach.
	Touched string
}

LayoutNode is what both arrangements need to know about one record.

type Manifest 

type Manifest struct {
	SchemaVersion int `json:"schema_version"`
	// Purpose documents this file for the humans who edit it. It is the one
	// field with nothing to consume it, by design: it is never rendered, and
	// the single-source rule would forbid rendering it if it were.
	Purpose   string     `json:"purpose"`
	Identity  BlockRef   `json:"identity"`
	UIStrings string     `json:"ui_strings"`
	Home      Home       `json:"home"`
	Record    RecordOpts `json:"record"`
	// Docs names the documentation pages the site's docs surface renders.
	// A docs.index says the site serves a /docs/ tree, so the header links it
	// and a link to a docs page reaches its route; without one both go
	// (iss-2609260928152365). The rest of the block is DEFERRED to the
	// docs-surface slice and validated here as paths.
	Docs DocsRefs `json:"docs"`
	// RecordPages carries the record explorer's selectors.
	// DEFERRED: consumed by spc-38's pages half; validated here as paths.
	RecordPages RecordPages `json:"record_pages"`
	// Checks declares which gates this repo arms.
	// DEFERRED: consumed by `abcd lint site` (spc-37, spc-38). The build
	// MEASURES the unresolved references and publishes the count; the ratchet
	// that refuses a larger one is that verb's.
	Checks ManifestGate `json:"checks"`
	// Pages switches pages of the closed page set off (itd-2609061543533170).
	// Absent, every page renders; the set is the same for every repository and
	// a switch can only take a page away, never add one.
	Pages PageSwitches `json:"pages"`
	// Hosting names where `abcd site setup` puts the rendered site. Absent,
	// setup derives it; the build never reads it.
	Hosting *Hosting `json:"hosting,omitempty"`
}

Manifest is `.abcd/site.json`.

Every field here is either CONSUMED by this build or DEFERRED to a named later slice — and a deferred field is still validated, so a typo in it fails today rather than in three slices' time. Nothing is parsed and quietly dropped: a key the binary reads but never acts on is indistinguishable, to the person who wrote it, from a key that works.

func LoadManifest 

func LoadManifest(repoRoot string) (Manifest, error)

LoadManifest reads and validates the composition manifest at repoRoot.

type ManifestGate 

type ManifestGate struct {
	EveryTextNodeHasSource        bool   `json:"every_text_node_has_source"`
	DocsLintOnRenderedText        bool   `json:"docs_lint_on_rendered_text"`
	CommandSnippetsPinnedToCLIRef bool   `json:"command_snippets_pinned_to_cli_reference"`
	UnresolvedReferenceBaseline   string `json:"unresolved_reference_baseline"`
}

ManifestGate is the check declaration. The gates themselves are a later slice; the manifest records which of them this repo arms.

type ModelTally 

type ModelTally struct {
	Model   string `json:"model"`
	Commits int    `json:"commits"`
}

ModelTally is one distinct `Assisted-by:` value and how often it appears.

type MonthMark 

type MonthMark struct {
	Month string `json:"month"`
	Node  int    `json:"node"`
}

MonthMark is the first record of a month, in placement order.

type PageSwitches added in v0.11.1 

type PageSwitches struct {
	Landing     *bool `json:"landing,omitempty"`
	Explorer    *bool `json:"explorer,omitempty"`
	RecordPages *bool `json:"record_pages,omitempty"`
	Graph       *bool `json:"graph,omitempty"`
	Timeline    *bool `json:"timeline,omitempty"`
	Glossary    *bool `json:"glossary,omitempty"`
	Status      *bool `json:"status,omitempty"`
}

PageSwitches is the `pages` block. A nil field is on.

type Panels 

type Panels struct {
	Latest string `json:"latest"`
	Health string `json:"health"`
	// Unresolved, Baseline and Isolated label the health summary's three
	// numbers; unlabelled they read as a rendering fault.
	Unresolved string `json:"unresolved"`
	Baseline   string `json:"baseline"`
	Isolated   string `json:"isolated"`
}

Panels captions the dashboard panels.

type Platform 

type Platform struct {
	DarwinARM64 string `json:"darwin-arm64"`
	DarwinAMD64 string `json:"darwin-amd64"`
	LinuxARM64  string `json:"linux-arm64"`
	LinuxAMD64  string `json:"linux-amd64"`
}

Platform names each released binary in the reader's own words.

type Point 

type Point struct {
	X float64 `json:"x"`
	Y float64 `json:"y"`
}

Point is one placed bubble centre, in the unit disk.

type PolicyRef 

type PolicyRef struct {
	File    string `json:"file"`
	Heading string `json:"heading"`
	Part    string `json:"part"`
}

PolicyRef selects a part of a span of a file by heading.

type RecordExport 

type RecordExport struct {
	SchemaVersion int `json:"schema_version"`
	// Build is the only non-derived content in the file: what produced it.
	Build BuildStamp `json:"build"`
	// Nodes are every record, ordered by store then id.
	Nodes []ExportNode `json:"nodes"`
	// Edges are the record's typed links, each distinct link appearing once.
	Edges []ExportEdge `json:"edges"`
	// Mentions are body references between records that no typed link already
	// records. They are undirected and deduplicated against Edges.
	Mentions []ExportMention `json:"mentions"`
	// Counts are the corpus by store and by lifecycle bucket.
	Counts Counts `json:"counts"`
	// Releases are the dated CHANGELOG headings, newest first. Absent where the
	// repository records none.
	Releases []changelog.DatedRelease `json:"releases"`
	// Authorship is who wrote the history and what assisted.
	Authorship Authorship `json:"authorship"`
	// Health is the record's own reference hygiene, measured.
	Health Health `json:"health"`
	// Layout carries the two precomputed arrangements.
	Layout Arrangements `json:"layout"`
	// History summarises the git walk the dates came from.
	History HistoryMeta `json:"history"`
}

RecordExport is record.json.

func BuildRecordExport 

func BuildRecordExport(repoRoot, baselineRel string, graph lint.RecordGraph, extra []lint.RecordNode, hist History, stamp BuildStamp, opts RecordOpts) (RecordExport, error)

BuildRecordExport derives record.json from the record graph, the git history and the changelog.

type RecordNav 

type RecordNav struct {
	Dashboard   string `json:"dashboard"`
	Graph       string `json:"graph"`
	Timeline    string `json:"timeline"`
	Foundations string `json:"foundations"`
	// Development names the deck of the stores that MOVE — intents, specs and
	// issues — as Foundations names the ones that hold.
	Development string `json:"development"`
	// Health names the page that collects every finding the record can be
	// checked against itself for.
	Health string `json:"health"`
	// Glossary names the page set that publishes the record's own terms — the
	// one place a word the record uses in more than one sense is pinned to a
	// spelling per sense.
	Glossary     string `json:"glossary"`
	Contributors string `json:"contributors"`
}

RecordNav labels the explorer's sub-navigation.

type RecordOpts 

type RecordOpts struct {
	IssueLedger bool `json:"issue_ledger"`
}

RecordOpts carries the working-tier publication opt-in (adr-32, itd-140).

type RecordPages 

type RecordPages struct {
	Contributors Contributors `json:"contributors"`
}

RecordPages carries the explorer pages' selectors.

type RecordUI 

type RecordUI struct {
	Frontmatter   string `json:"frontmatter"`
	Inbound       string `json:"inbound"`
	Outbound      string `json:"outbound"`
	Mentions      string `json:"mentions"`
	NotInTree     string `json:"not_in_tree"`
	OpenOnForge   string `json:"open_on_forge"`
	CommitHistory string `json:"commit_history"`
}

RecordUI labels a per-record page's sections.

type Relations 

type Relations struct {
	BlockedBy  string `json:"blocked_by"`
	Supersedes string `json:"supersedes"`
	Implements string `json:"implements"`
	BuildsOn   string `json:"builds_on"`
}

Relations names each directed link read from its target's side.

func (Relations) Inverse 

func (r Relations) Inverse(rel string) string

Inverse names a directed relation read from the record it points at. An undirected relation reads the same from both ends and is returned unchanged.

type Release 

type Release struct {
	From   string `json:"from"`
	Assets string `json:"assets"`
}

Release names where the install chapter reads version and asset names from.

type Renderer 

type Renderer struct {
	// UI is the closed allowlist of interface strings; the renderer adds the
	// copy-button label and nothing else.
	UI UI
	// Image renders one image reference. src is as written in the markdown,
	// relative to the page; alt is its alt text.
	Image func(src, alt string, at Source) (string, error)
	// Link rewrites one href. It never fails: an href it does not recognise is
	// left exactly as the record wrote it.
	Link func(href string, at Source) string
	// Refs are the document's link reference definitions, from LinkDefinitions.
	// A nil map means the document defines none, and every reference link in it
	// is a refusal.
	Refs map[string]string
}

Renderer turns the markdown subset into the site's HTML. Its two hooks are the places the site differs from a generic renderer: an image becomes a committed asset (inlined SVG or copied raster) rather than a bare <img>, and a repo-relative link becomes a site route.

func (*Renderer) RenderBlock 

func (r *Renderer) RenderBlock(path string, blk Block) (string, error)

RenderBlock renders one top-level block.

func (*Renderer) RenderBlocks 

func (r *Renderer) RenderBlocks(path string, blocks []Block) (string, error)

RenderBlocks renders a block sequence in order.

type RepoMeta 

type RepoMeta struct {
	Name       string `json:"name"`
	Repository string `json:"repository"`
	License    string `json:"license"`
	Author     struct {
		Name string `json:"name"`
	} `json:"author"`
	// AuthorName flattens Author.Name for the footer.
	AuthorName string `json:"-"`
}

RepoMeta is the package metadata the site links and credits from.

func LoadRepoMeta 

func LoadRepoMeta(repoRoot string) (RepoMeta, error)

LoadRepoMeta reads the package manifest. An absent one is a state: the pages that would carry a forge link render without it.

type Request 

type Request struct {
	// RepoRoot is the repository to render.
	RepoRoot string
	// OutDir is where to write, absolute or relative to the caller's cwd.
	OutDir string
	// Stamp is the build metadata the footer and record.json carry. Every field
	// is injected so a test can pin the output byte for byte; empty fields are
	// filled from the repository (the version from the changelog, the commit
	// from git HEAD).
	Stamp BuildStamp
	// Lanes reads the build's state file for the Status page's Now / Next /
	// Later block (itd-2609212103568351); nil reads as an absent state file.
	// The front door hands in the implement loop's reader, which this package
	// cannot import.
	Lanes statusblock.LaneReader
	// LeaveUI renders without completing the repository's ui.json: the gate's
	// own render (Check) writes only inside its output directory, so an older
	// file is refused there by name and completed by `site build` or
	// `site setup` alone.
	LeaveUI bool
}

Request is one build.

type Result 

type Result struct {
	OutDir string `json:"out_dir"`
	// Files are the output-relative paths written, sorted.
	Files []string `json:"files"`
	// Bytes is the total size written.
	Bytes int64 `json:"bytes"`
	// Pages is how many HTML pages the explorer rendered, beyond the landing
	// page: one per route and one per record.
	Pages int `json:"pages"`
	// Records, Links and Mentions summarise the exported graph.
	Records  int `json:"records"`
	Links    int `json:"links"`
	Mentions int `json:"mentions"`
	// Unresolved is the number of typed references the record cannot account
	// for; Baseline the committed ratchet's size.
	Unresolved int `json:"unresolved"`
	Baseline   int `json:"baseline"`
	// Overlaps is the packing's sanity count over BOTH arrangements. It is zero
	// or the chart is wrong, and it is reported rather than assumed.
	Overlaps int `json:"overlaps"`
	// Version and Commit are what the footer says the site was built from.
	Version string `json:"version"`
	Commit  string `json:"commit"`
	// AddedLabels names each interface label the build added to the
	// repository's ui.json, LabelsFile, because the file declared none for it
	// (the TG1 ruling). Both are empty when nothing was added.
	AddedLabels []string `json:"added_labels,omitempty"`
	LabelsFile  string   `json:"labels_file,omitempty"`
}

Result describes what a build wrote.

func Build 

func Build(req Request) (Result, error)

Build renders the site into req.OutDir. A failure after it completed the repository's ui.json is a *LabelsAddedError, so the change it took is never silent (ADR 2609301720596683).

type Section 

type Section struct {
	// Level is the heading depth (1..6), or 0 for the implicit preamble.
	Level int
	// Title is the heading text, trimmed.
	Title string
	// Anchor is slug(Title).
	Anchor string
	// Body is the text between this heading and the next, with leading and
	// trailing blank lines removed.
	Body string
	// Line is the 1-based source line of the heading (0 for the preamble).
	Line int
	// BodyLine is the 1-based source line Body starts at.
	BodyLine int
}

Section is one heading and the body that follows it, down to the next heading. The first section of a document is the implicit preamble: level 0, no title, and whatever text precedes the first heading. A document whose first line is an H1 therefore yields no preamble section at all, because the walk drops a level-0 section with an empty body.

func Sections 

func Sections(path, md string, offset int) ([]Section, error)

Sections splits markdown into its headings and their bodies, honouring fenced code and HTML comments so a `#` comment inside a shell block, or a heading parked in a comment, is never read as a heading. offset is the number of lines already consumed ahead of md (the frontmatter), so the reported lines are the ones a reader would find in the file.

Fences and comments are read by mdrecord's ListNested rule — CommonMark's fence rule plus a fence indented under a list item, which the record writes — so this walk agrees with every other reader of a record body about which lines are live (iss-2609250955051598).

A span that never closes is refused, naming the line that opened it. It is the quietest failure this walk has: once a fence or a comment is open no later heading is a heading, so every section after it silently ceases to exist and the page renders a document that is short in a way nobody notices. Refusing costs one edit; not refusing costs a missing chapter nobody is looking for.

type SetupRequest added in v0.11.1 

type SetupRequest struct {
	// RepoRoot is any directory inside the repository.
	RepoRoot string
	// Name and Domain seed the hosting block when the composition has none.
	// Name defaults to the repository's own name.
	Name, Domain string
	// Confirm replaces machinery that drifted from what setup writes.
	Confirm bool
	// Asker confirms each remote write; nil declines them all.
	Asker Asker
	// Forge is the repository's forge; nil resolves GitHub through gh.
	Forge Forge
	// ConfirmTool answers the offer to install a missing gh when Forge is nil
	// (the DQ3 ruling); nil asks no one, so nothing is installed.
	ConfirmTool tools.Confirm
	// Credentials resolves the hosting credential by name; nil is this
	// machine's store.
	Credentials credential.Source
	// Adapter overrides the provider the composition names (tests point it at
	// a fake); nil resolves the composition's provider from the list.
	Adapter hosting.Adapter
	Context context.Context
}

SetupRequest is one run of the verb.

type SetupResult added in v0.11.1 

type SetupResult struct {
	Status       string                 `json:"status"`
	Repo         string                 `json:"repo,omitempty"`
	Files        []scaffold.FileOutcome `json:"files"`
	Environments []EnvironmentOutcome   `json:"environments"`
	Host         HostOutcome            `json:"host"`
	// AddedLabels names each interface label setup added to a ui.json the
	// repository already had, LabelsFile (the TG1 ruling). Both are empty when
	// nothing was added.
	AddedLabels []string `json:"added_labels,omitempty"`
	LabelsFile  string   `json:"labels_file,omitempty"`
	// Remaining are the exact steps left for the person, in order.
	Remaining []string `json:"remaining,omitempty"`
	// Notes say what the verb deliberately did not do, and why.
	Notes []string `json:"notes,omitempty"`
}

SetupResult is what the verb did, stage by stage, and what remains.

func Setup added in v0.11.1 

func Setup(req SetupRequest) (SetupResult, error)

Setup runs the verb. It returns an error only for a gate that stops it before any stage runs; every later failure is a refused stage in the result.

type Source 

type Source = mdrender.Source

Source is a position in a repository file.

type Status 

type Status struct {
	Manifest  bool   `json:"manifest"`
	UIStrings bool   `json:"ui_strings"`
	UIPath    string `json:"ui_strings_path,omitempty"`
	Baseline  bool   `json:"baseline"`
	BaselineN int    `json:"baseline_entries"`
	// BaselinePath is the ratchet the board actually read: the manifest's
	// declaration where it makes one, the default otherwise.
	BaselinePath string `json:"baseline_path"`
	OutDir       string `json:"out_dir"`
	OutExists    bool   `json:"out_exists"`
	OutFiles     int    `json:"out_files"`
	// OutRefused is why the board did not look inside the output directory:
	// the same gate the build applies, reported rather than raised, because a
	// board that exits non-zero answers the question by refusing to answer it.
	OutRefused string `json:"out_refused,omitempty"`
	Chapters   int    `json:"chapters"`
	IssueLedge bool   `json:"issue_ledger"`
	Version    string `json:"version"`
	Commit     string `json:"commit"`
}

Status is the read-only board the bare verb renders: what the repository has declared, and what the last build left behind.

func Describe 

func Describe(repoRoot, outDir string) (Status, error)

Describe reads the site's declared state without writing anything.

type StatusUI added in v0.12.0 

type StatusUI struct {
	Now   string `json:"now"`
	Next  string `json:"next"`
	Later string `json:"later"`
	// NextUp marks the pick order's head on Now.
	NextUp string `json:"next_up"`
	// Fails leads the gating readiness checks a Later intent fails.
	Fails string `json:"fails"`
	// Draft marks a Later row that is a draft.
	Draft string `json:"draft"`
	// Target leads the release a row's intent targets (itd-2609212103572513).
	Target string `json:"target"`
	// None stands in an empty list.
	None string `json:"none"`
	// OrderRecordID is the note a block read oldest id first carried. The
	// block is read in the pick order, the one order it has, so no page renders
	// it; the key stays declared because the file is decoded with unknown
	// fields refused, and a managed repository's ui.json that declares it must
	// still build.
	OrderRecordID string `json:"order_record_id"`
}

StatusUI labels the Now / Next / Later block (itd-2609212103568351).

type Tiles 

type Tiles struct {
	Releases   string `json:"releases"`
	ADR        string `json:"adr"`
	Intent     string `json:"intent"`
	Spec       string `json:"spec"`
	Issue      string `json:"issue"`
	Principle  string `json:"principle"`
	Discipline string `json:"discipline"`
	Commits    string `json:"commits"`
}

Tiles captions the record dashboard's counts.

func (Tiles) ForType 

func (t Tiles) ForType(typ string) string

ForType captions one record store's count. A store with no caption is named by the store itself, which is a fact about the record rather than a word the generator wrote.

type UI 

type UI struct {
	Purpose       string `json:"_purpose"`
	NavStory      string `json:"nav_story"`
	NavInstall    string `json:"nav_install"`
	NavDocs       string `json:"nav_docs"`
	NavRecord     string `json:"nav_record"`
	NavReferences string `json:"nav_references"`
	CTARoles      string `json:"cta_roles"`
	CTAInstall    string `json:"cta_install"`
	CTADocs       string `json:"cta_docs"`
	RecordLink    string `json:"record_link"`
	FromTheRecord string `json:"from_the_record"`
	LatestRelease string `json:"latest_release"`
	AllReleases   string `json:"all_releases"`
	Copy          string `json:"copy"`
	Copied        string `json:"copied"`
	SearchDocs    string `json:"search_docs"`
	// ForgeNames names each forge host the header and footer links may label —
	// "GitHub" for github.com. A host the map does not name keeps the owner/name
	// handle, so the generic explorer never assumes a forge. The map may be
	// empty; the missing-string check walks only declared strings.
	ForgeNames map[string]string `json:"forge_names"`
	Platform   Platform          `json:"platform"`
	Tiles      Tiles             `json:"tiles"`
	// RecordNav labels the explorer's sub-navigation; each label is also that
	// page's own heading, so a page and the tab that reaches it cannot drift.
	RecordNav RecordNav `json:"record_nav"`
	// Panels captions the dashboard's panels that no count names.
	Panels Panels `json:"panels"`
	// Graph labels the relationship chart's controls.
	Graph GraphUI `json:"graph"`
	// Record labels the per-record page's own sections.
	Record RecordUI `json:"record"`
	// Relations names a typed link read from the far end. The forward name is
	// the relation's own word from the record; only the inverse needs saying.
	Relations Relations `json:"relations"`
	// Contributors labels the attribution page's two rows and two figures.
	Contributors ContributorsUI `json:"contributors"`
	// Health labels each family of finding the record is checked for.
	Health HealthUI `json:"health"`
	// Status labels the Now / Next / Later block the Status page opens with.
	Status        StatusUI `json:"status"`
	More          string   `json:"more"`
	Standby       string   `json:"standby"`
	CLIGroup      string   `json:"cli_group"`
	MatchesSystem string   `json:"matches_system"`
	// ReadScript labels the link beside the install command that opens the
	// script the command runs. It is an invitation to read before running, so it
	// says what the reader would do, not what the file is.
	ReadScript string `json:"read_script"`
	// Unreleased stands where the version goes on a build of an untagged tree.
	// It is a word rather than a blank because a stamp reading "· · abcdef1"
	// looks like a rendering fault, and one reading "v0.6.1" would be a lie.
	Unreleased string `json:"unreleased"`
	Beta       string `json:"beta"`
}

UI is the interface-string allowlist.

func LoadUI 

func LoadUI(repoRoot, rel string) (UI, error)

LoadUI reads the interface-string allowlist named by the manifest.

type UnsupportedError 

type UnsupportedError = mdrender.UnsupportedError

UnsupportedError is a markdown construct outside the rendered subset.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.