extract

Documentation

Overview

Package extract holds the readers of specarch extract. Each reads one surface of an existing system into a partial specification tree, at the commit that names what was read (docs/extraction.md, Building extract).

Index

• Constants
• Variables
• func DumpFormat(path string) (string, error)
• func WriteFragment(path string, n *yaml.Node, note string) error
• type Difference
  • func CheckCatalogue(dumpPath string, tables []gensql.Table) ([]Difference, error)
  • func CheckGrants(dumpPath string, root *yaml.Node) ([]Difference, error)
  • func CheckRoutes(dumpPath string, root *yaml.Node, implementations []*yaml.Node) ([]Difference, error)
  • func (d Difference) ID() string
• type DocumentOptions
• type Read
  • func Open(paths []string) (*Read, error)
  • func (r *Read) Exists(commit string) bool
  • func (r *Read) LastChange(path string) (string, error)
• type Refusal
  • func (r *Refusal) Error() string
• type Repository
• type Result
  • func Dart(dumpPath, out, key, implementation string) (*Result, error)
  • func Database(dumpPath, out, key string, fragment bool) (*Result, error)
  • func Documents(path, out string, opts DocumentOptions) (*Result, error)
  • func Go(paths []string, out, key, implementation string, writeImplementation bool) (*Result, error)
  • func JavaScript(dumpPath, out, key, implementation string) (*Result, error)
  • func Merge(specs []*spec.Spec, out string, vocabularies []*vocabulary.Vocabulary) (*Result, error)
  • func OpenAPI(path, out, key string) (*Result, error)
  • func Outline(paths []string, out, key string) (*Result, error)
  • func Pages(root, out, key, facts, implementation string) (*Result, error)
  • func Permissions(dumpPath, routesPath, out, key string) (*Result, error)
  • func Router(dumpPath, out, key string) (*Result, error)
  • func Swift(dumpPath, out, key, implementation string) (*Result, error)
  • func WorkflowTable(dumpPath, out, key string) (*Result, error)
  • func Workflows(path, out, key string) (*Result, error)
• type Tree
  • func (t *Tree) Files() []string
  • func (t *Tree) ListStage(stage string)
  • func (t *Tree) Write(out string) error

Constants

const (
	RouteTableDump      = "route table"
	PermissionTableDump = "permission table"
	CatalogueDump       = "catalogue dump"
)

The formats of the dumps check reads, by the key that names each.

Variables

var RuleFormats = map[string]string{
	"operation_not_served":             RouteTableDump,
	"route_not_specified":              RouteTableDump,
	"operation_permission_differs":     RouteTableDump,
	"grant_not_in_code":                PermissionTableDump,
	"grant_not_specified":              PermissionTableDump,
	"table_not_in_database":            CatalogueDump,
	"table_not_specified":              CatalogueDump,
	"column_not_in_database":           CatalogueDump,
	"column_not_specified":             CatalogueDump,
	"column_type_differs":              CatalogueDump,
	"column_nullability_differs":       CatalogueDump,
	"column_generated_default_differs": CatalogueDump,
	"foreign_key_not_in_database":      CatalogueDump,
	"foreign_key_not_specified":        CatalogueDump,
	"foreign_key_differs":              CatalogueDump,
	"unique_not_in_database":           CatalogueDump,
	"unique_not_specified":             CatalogueDump,
	"check_not_in_database":            CatalogueDump,
	"check_not_specified":              CatalogueDump,
	"check_expression_differs":         CatalogueDump,
	"index_not_in_database":            CatalogueDump,
	"index_differs":                    CatalogueDump,
	"index_not_listed":                 CatalogueDump,
}

RuleFormats are the rules of check's differences, each with the format of the dump it compares.

Functions

func DumpFormat

func DumpFormat(path string) (string, error)

DumpFormat is the format of a dump, by the key that names it.

func WriteFragment

func WriteFragment(path string, n *yaml.Node, note string) error

WriteFragment writes an implementation fragment a reader wrote, with the note as its first comment.

Types

type Difference

type Difference struct {
	Rule    string
	Subject string // what it is about, by the matching: POST /loans, members.phone_number
	Message string
	Report  bool // a report: printed as a warning, never a failure
	// Pointer is the specification's entry it is at, or "" for one only
	// the dump has, which is at Line and Column of the dump File.
	Pointer      string
	File         string
	Line, Column int
	DumpPointer  string // the entry's pointer in the dump
}

Difference is one thing a dump and the specification disagree on.

func CheckCatalogue

func CheckCatalogue(dumpPath string, tables []gensql.Table) ([]Difference, error)

CheckCatalogue compares a catalogue dump with the tables specarch generate sql writes for PostgreSQL: a table by its name and a column by its table and name, and their types, nullability, generated defaults, keys, constraints and listed indexes.

func CheckGrants

func CheckGrants(dumpPath string, root *yaml.Node) ([]Difference, error)

CheckGrants compares a permission table with the roles of the specification: a grant by its role and permission. A grant one side declares is held by the other when it grants it, itself or through a permission it grants that implies it, by the specification's implies (ADR-100). A grant of public is no grant, and the gates are not compared.

func CheckRoutes

func CheckRoutes(dumpPath string, root *yaml.Node, implementations []*yaml.Node) ([]Difference, error)

CheckRoutes compares a route table with the specification's operations: an operation by its method and path, and the permission it checks. Under bindings.http.listRoutes, each list served by GET is served by POST at its twin's path too (ADR-121); an operation another stakeholder owns is not compared.

func (Difference) ID

func (d Difference) ID() string

ID is the difference's id: its rule and what it is about, the same wherever the entry is written.

type DocumentOptions

type DocumentOptions struct {
	Key          string                 // the source key, or "" for the file's name
	Vocabulary   *vocabulary.Vocabulary // the words named with --language or --vocabulary, or nil for English
	GivenOutside bool                   // the document was given to parties outside
}

DocumentOptions are what extract documents is told beside the path.

type Read

type Read struct {
	Repository Repository
	Paths      []string // from the repository's root, slash-separated
	Files      []string // the tracked files under Paths, sorted
	Commit     string   // the newest of the commits that last changed each path
}

Read is what a reader read in a repository: the paths from its root, the tracked files under them, and the commit that names them.

func Open

func Open(paths []string) (*Read, error)

Open finds the repository holding the paths and checks that a commit names what is under them: every path is in that one repository, tracked, with no change not committed and no file that is neither tracked nor ignored, and the clone is not shallow.

func (*Read) Exists

func (r *Read) Exists(commit string) bool

Exists says whether a commit is in the repository's history.

func (*Read) LastChange

func (r *Read) LastChange(path string) (string, error)

LastChange is the commit that last changed a path from the repository's root, or "" when none has.

type Refusal

type Refusal struct{ Reason string }

Refusal is a source that cannot be read as the reader expects: no commit names it, or its content is not what the reader takes. It is exit status 1; any other error is status 2.

func (*Refusal) Error

func (r *Refusal) Error() string

type Repository

type Repository struct {
	Root string // the repository's folder, with symbolic links resolved
}

Repository is the git repository a reader reads from: the one holding the paths, a submodule's own when they are in one.

type Result

type Result struct {
	Tree  *Tree
	Lines []string
	// Implementation is the implementation fragment a reader wrote, or
	// nil, and ImplementationNote the comment above it.
	Implementation     *yaml.Node
	ImplementationNote string
}

Result is what a reader wrote and what it prints: the tree, and the lines of its standard output in order.

func Dart

func Dart(dumpPath, out, key, implementation string) (*Result, error)

Dart reads a code-facts dump of Dart source (ADR-092): go_router's and Navigator's screens with their fields and titles, json_serializable and freezed models, retrofit, dio and http clients, shelf_router and dart_frog routes with the project's named check, and the settings fromEnvironment and Platform.environment give, each citing its file and line.

func Database

func Database(dumpPath, out, key string, fragment bool) (*Result, error)

Database reads a catalogue dump into entities, one per table. With fragment, the mappings it knows, each table and its plain indexes, go into Result.Implementation, the implementation fragment --implementation-out names (ADR-121).

func Documents

func Documents(path, out string, opts DocumentOptions) (*Result, error)

Documents reads one Markdown document into a tree: its outline as the clauses of one document source, every commitment sentence as a requirement, and every table with a known header as an entity's fields, by the words of the vocabulary named, or English.

func Go

func Go(paths []string, out, key, implementation string, writeImplementation bool) (*Result, error)

Go reads the tracked Go files under the paths with the standard library's parser (ADR-075), and dxlib's registration calls in them (ADR-076): each endpoint NewEndPoint registers with literal values is an operation citing its file and line, with its handler's parameter reads and the problems it answers.

func JavaScript

func JavaScript(dumpPath, out, key, implementation string) (*Result, error)

JavaScript reads a code-facts dump of JavaScript and TypeScript source (ADR-089): Express and Fastify routes with the permission checks the implementation file names, the bodies a handler validates or declares, the schemas of zod, yup, joi and JSON Schema, React Router's screens with their fields, titles and links, fetch and axios clients, the environment the code reads, and message catalogues, each citing its file and line.

func Merge

func Merge(specs []*spec.Spec, out string, vocabularies []*vocabulary.Vocabulary) (*Result, error)

Merge merges the trees, each a specification that tracks origin and that validate accepts, into one written into out (docs/from-sources.md, section 3.2; ADR-045).

func OpenAPI

func OpenAPI(path, out, key string) (*Result, error)

OpenAPI reads one OpenAPI 3.0 or 3.1 document into a tree: its operations under their paths, its component schemas as entities, schemas and enums, and a question for what the document does not say (ADR-049).

func Outline

func Outline(paths []string, out, key string) (*Result, error)

Outline reads the tracked files under the paths into a tree that lists them as clauses of one code source and holds no element, so that specarch gaps shows each as producing nothing until a reader reads it.

func Pages

func Pages(root, out, key, facts, implementation string) (*Result, error)

Pages reads a file-system router's root folder into one page per file or folder it serves a page from, with the content of each page that has a schema file from it, and one operation per route file whose name gives its method. The router is told by the folder's name (ADR-084).

func Permissions

func Permissions(dumpPath, routesPath, out, key string) (*Result, error)

Permissions reads a permission table into roles and the permissions each grants, and asks about every check the table says a setting switches off or one kind of caller skips. Given the route table too (routesPath), it writes the routes' operations as extract router does, each route that checks no permission taking the one the table's rules give it (ADR-100).

func Router

func Router(dumpPath, out, key string) (*Result, error)

Router reads a route table into operations, one per method and path pair, with their path parameters and the permission each checks.

func Swift

func Swift(dumpPath, out, key, implementation string) (*Result, error)

Swift reads a code-facts dump of Swift source (ADR-087): SwiftUI screens, their navigation and fields, SwiftData, Codable and Core Data models, URLSession clients, Vapor routes, and the settings Info.plist, .xcconfig files and the code give, each citing its file and line.

func WorkflowTable

func WorkflowTable(dumpPath, out, key string) (*Result, error)

WorkflowTable reads a workflow table into one workflow per workflow it lists, with the questions the BPMN reader asks: the trigger's and each operation step's operation left out with a must question carrying the name under names, which specarch merge fills from the tree that declares it, and the subject and each approval's permission asked for.

func Workflows

func Workflows(path, out, key string) (*Result, error)

Workflows reads a BPMN 2.0 XML file into one workflow per process, in the sequential subset of ADR-054: a start event whose message names the trigger's operation, user tasks as approvals with their potential owners and a timer, service tasks as operation steps, and an exclusive gateway after an approval that ends the request when it is refused.

type Tree

type Tree struct {
	// contains filtered or unexported fields
}

Tree is a specification tree being written: its files by their path from the tree's root.

func (*Tree) Files

func (t *Tree) Files() []string

Files is the tree's file names, sorted.

func (*Tree) ListStage

func (t *Tree) ListStage(stage string)

ListStage lists a stage among the root file's stages, in life-cycle order, when it is not there yet.

func (*Tree) Write

func (t *Tree) Write(out string) error

Write writes the tree into out, creating the folder. It writes only its own files; it never removes one. Before writing, every source's outline is completed with the clauses the tree cites of it, and every question's pointer is anchored in the tree.