generate

package
v0.7.1 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package generate writes documents from SpecArch files. The techspec target writes an arc42 technical specification in Markdown with Mermaid diagrams, and rewrites the generated regions of hand-written Markdown.

Index

Constants

View Source 
const CompanionName = "specarch.md"

CompanionName is the hand-written explanation beside a specification's root file, whose marked regions the techspec target rewrites.

View Source 
const EstateName = "estate.md"

EstateName is the file the module map of an estate is written to, beside the modules' own documents.

Variables

View Source 
var (
	DocumentTargets = []string{"techspec", "requirements", "testplan", "traceability", "deployment", "commissioning", "handover", "questions", "problems", "changes", "releases", "html", "manual", "operations"}
	BuiltDocuments  = map[string]bool{"techspec": true, "requirements": true, "testplan": true, "traceability": true, "deployment": true, "commissioning": true, "handover": true, "questions": true, "problems": true, "changes": true, "releases": true, "html": true}
)

DocumentTargets are the document targets of the design, in the order they are listed; BuiltDocuments says which this program has.

Functions

func Changes added in v0.3.0 

func Changes(root *yaml.Node, relRoot string, state *State) string

Changes writes the change and defect register from the records.

func Commissioning 

func Commissioning(root *yaml.Node, relRoot string, impls []Implementation, state *State) string

Commissioning writes the commissioning test procedure, one section per environment in the order a release reaches them, with a column for each step's result, and the sign-off sheet.

func DeploymentGuide 

func DeploymentGuide(root *yaml.Node, relRoot string, impls []Implementation, state *State) string

DeploymentGuide writes the deployment guide: the environments and the promotion path, the settings and their values in each installation, the installations of each implementation, then release, rollback and the migrations.

func Document 

func Document(target string, root *yaml.Node, relRoot string, impls []Implementation, state *State) (text string, ok bool)

Document writes the document of a target from a specification and its implementation files. ok is false for a target this package does not write.

func DocumentName 

func DocumentName(target string) string

DocumentName is the file a target writes in the folder it owns.

func Estate added in v0.7.0 

func Estate(root *yaml.Node, relEstate string, modules []EstateModule, marks []Mark) string

Estate writes the module map of an estate (ADR-113): the modules with the version each is held at, and the references between them through their dependencies, drawn as the context diagram. marks are the estate's own problems, each shown at its module.

func Handover added in v0.7.0 

func Handover(root *yaml.Node, relRoot string, impls []Implementation, state *State) string

Handover writes the handover document for the engineers of the customer who runs an environment (ADR-129): what they receive, what stays whose responsibility, how each implementation builds a release and the licences of its dependencies, what the hosts must provide, every setting, the migrations, how a release is installed and rolled back, backup and restore, what is watched, the checks to run after installing, the acceptance tests and the sign-off sheet, in plain words for a reader who knows nothing of SpecArch.

func Holding added in v0.2.0 

func Holding(root *yaml.Node, impls []Implementation, target string) []string

Holding lists the open must and should questions that block what a code target reads: the sections its implementation files declare under targets.<name>.reads, or every section when none does.

func IsDocumentTarget added in v0.2.0 

func IsDocumentTarget(t string) bool

IsDocumentTarget reports whether a target name is a document's.

func Questions added in v0.2.0 

func Questions(root *yaml.Node, relRoot string, impls []Implementation, state *State) string

Questions writes the open questions document, which specarch gaps also prints: the counts, the questions by stage, and which outputs are ready, drafts or waiting.

func Releases added in v0.3.0 

func Releases(root *yaml.Node, relRoot string, state *State) string

Releases writes the release notes from the records, newest first.

func Requirements 

func Requirements(root *yaml.Node, relRoot string, impls []Implementation, state *State) string

Requirements writes the requirements specification: the stakeholders, their needs, and the requirements with every attribute, in the order of a requirements specification of ISO/IEC/IEEE 29148.

func Site added in v0.6.0 

func Site(root *yaml.Node, relRoot string, impls []Implementation, state *State) string

Site writes the specification as one HTML page that needs no server and makes no request: an overview first, then every section with an anchor at every element, named by its pointer, the problems linked both ways with the entries they mark, a search and light and dark colours.

func Techspec 

func Techspec(root *yaml.Node, relRoot string, impls []Implementation, state *State) string

Techspec writes the technical specification of one specification: its merged document and its implementation files. relRoot is the root file's path as seen from the output folder; it goes into the header.

func Testplan 

func Testplan(root *yaml.Node, relRoot string, impls []Implementation, state *State) string

Testplan writes the test plan and the test case specifications: the levels, how each implementation runs the tests, then every design test grouped by its subject, then the derived cases left out.

func Traceability 

func Traceability(root *yaml.Node, relRoot string, impls []Implementation, state *State) string

Traceability writes the traceability matrix from needs through requirements to what satisfies and verifies them, and lists the gaps. It names elements by ID only; their Insights are in the documents that describe them.

Types

type EstateModule added in v0.7.0 

type EstateModule struct {
	Key      string
	Location string     // as the estate writes it
	Version  string     // the version the estate lists
	About    string     // the estate's description of it
	RelRoot  string     // its root file from the document's folder; "" when it was not found
	Root     *yaml.Node // its specification; nil when it was not found or did not parse
}

EstateModule is one module an estate lists, as the module map shows it.

type IdiomUse added in v0.4.0 

type IdiomUse struct {
	Name, Version, As, From, Why string
	Parts                        []string
}

IdiomUse is one idiom as an implementation file uses it: shipped, overridden (with the parts the project replaces and the version it copied), the project's own, or excluded, with the reason.

type Implementation 

type Implementation struct {
	Node   *yaml.Node
	Rel    string
	Path   string
	Idioms []IdiomUse // the idioms the file uses, as the validator resolves them
}

Implementation is one implementation file of the specification, parsed. Rel is its path as seen from the output folder; Path as given.

type LeftOut added in v0.3.0 

type LeftOut struct {
	Subject, Case, Scenario, Reason string
}

LeftOut is one derived case the test plan lists as left out.

type Listed added in v0.6.0 

type Listed struct {
	ID, Severity, Rule, Message string
	// Line is the problem's line in the problems file, and Notes its
	// notes there.
	Line    string
	Notes   []string
	Pointer string
}

Listed is one problem as the problems file lists it, and the pointer of the entry it marks ("" for one outside the specification).

type Mark added in v0.6.0 

type Mark struct {
	Severity     string // error or warning
	File         string // as the document names it, from its folder
	Line, Column int
	// Pointer leads into the merged specification; it is "" when the
	// problem is in a file outside it, such as an implementation file or a
	// record.
	Pointer           string
	Rule, Message, ID string
}

Mark is one error or warning of the specification as a document marks it (ADR-065): a Problem paragraph at the element its pointer leads to, or under the document's summary when the document shows no element for it.

func (Mark) String added in v0.6.0 

func (m Mark) String() string

String is the problem line: file:line:column: severity: pointer: rule: message [id].

type MarkerError 

type MarkerError struct {
	Line    int
	Message string
}

MarkerError is a problem with the markers of a hand-written document.

func RewriteMarkers 

func RewriteMarkers(text string, design *yaml.Node) (string, []MarkerError)

RewriteMarkers replaces the text between each pair of markers with what the begin marker names, drawn from the design file, and leaves every other line as it is. It follows the markersWellFormed algorithm: regions never nest, every begin has an end, and a marker for an object that does not exist is an error, never an empty block.

type Reference added in v0.7.0 

type Reference struct {
	Path, Text, Specification, Version, Waits string
}

Reference is one reference into another specification that waits: the specification is not given, or the element is blocked there.

type SiteParts added in v0.6.0 

type SiteParts struct {
	// Workflows are each workflow's diagram as specarch-gen-bpmn draws it
	// in SVG, by the workflow's name.
	Workflows map[string]string
	// Previews are each page's screen as specarch-gen-ui writes it, with
	// its style sheet inside and its scripts left out, by the page's name.
	Previews map[string]string
	// NoPreview says, by page name, why a page has no screen preview, and
	// NoPreviews why no page has one, when that is so.
	NoPreview  map[string]string
	NoPreviews string
	// Problems are every error, warning and open question in the order of
	// the problems file.
	Problems []Listed
}

SiteParts are what the html target shows that other generators make, and the problems it lists; specarch gathers them before the page is written.

type State added in v0.2.0 

type State struct {
	Missing  map[string][]string // element pointer -> the keys missing there, as the validator found them
	Approval string              // one sentence: approved on, not approved because
	Approved bool
	LeftOut  []LeftOut // the derived cases of rank other no test covers, for the test plan
	// Records are the record files beside the specification, parsed, in
	// path order, and RecordsRel their folder as the document names it.
	Records    []*yaml.Node
	RecordsRel string
	// StatePaths are, per entity with a state machine, its paths from an
	// initial to a terminal state, for the test plan.
	StatePaths map[string][]string
	// Places are, per block of a question that names what the source
	// gives, the file and line of the element whose key it leaves out.
	Places map[string]string
	// Marks are the errors and warnings of the specification, which the
	// documents mark at their elements.
	Marks []Mark

	// Site is what the html target shows that other generators make, and
	// the problems it lists.
	Site *SiteParts
	// References are the references into other specifications that the
	// run could not resolve, in document order.
	References []Reference
	// Withheld is, for a document for everyone, the internal elements it
	// left out (ADR-119); nil for a document that holds every element.
	Withheld *Withheld
	// contains filtered or unexported fields
}

State is what the questions document needs beyond the specification: the keys the open questions cover, and where the approval stands.

type Withheld added in v0.7.0 

type Withheld struct {
	Pointers []string
	// Questions are the pointers of the open questions left out, whose
	// every pointer is at or under an element left out.
	Questions []string
	Sections  []string       // the sections that lost an element, in document order
	Counts    map[string]int // by section
	// contains filtered or unexported fields
}

Withheld is what a document for everyone leaves out (ADR-119): the pointer of every internal element, outermost only, and how many each section lost, in document order.

func ForEveryone added in v0.7.0 

func ForEveryone(root *yaml.Node) (*yaml.Node, *Withheld)

ForEveryone is the specification as a document for everyone reads it: every element whose audience is internal left out, with what is inside it; the satisfies, verifies and needs entries that name a requirement or need left out; and the open questions whose every pointer is at or under an element left out. The nodes that stay are the specification's own, so their pointers do not change.

func (*Withheld) Covers added in v0.7.0 

func (w *Withheld) Covers(ptr string) bool

Covers reports whether a pointer is at or under an element left out.

func (*Withheld) ForEveryoneImplementation added in v0.7.0 

func (w *Withheld) ForEveryoneImplementation(root *yaml.Node) *yaml.Node

ForEveryoneImplementation is an implementation file as a document for everyone reads it: the mappings of an element left out are left out, and so are the satisfies entries that name a requirement left out.

func (*Withheld) Total added in v0.7.0 

func (w *Withheld) Total() int

Total is the number of elements left out.

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.