Skip to content

Module github.com/bide-ai/bide/flowedit ​

Go module github.com/bide-ai/bide/flowedit; all modules.

flowedit ​

github.com/bide-ai/bide/flowedit · pkg.go.dev · Stability: experimental

Package flowedit is the edit engine of the flow editor (docs/design/visual-editor.md): it applies one operation to the text of a flow config by splicing, so every byte outside the edit is the original byte, and it returns the text only after checking that the result means what the operation says (it re-parses the result and compares it with the operation applied to the data).

Constants

  • const ConfirmWeakens = "weakens": ConfirmWeakens: the text is weaker than the baseline.
  • const ConfirmUncertified = "uncertified": ConfirmUncertified: the text has errors against the program's blocks, so the comparison was made without what they declare in Go (typed mode).
  • const ConfirmUncompared = "uncompared": ConfirmUncompared: the text could not be compared with the baseline.
  • const MaxBodySize = 6*MaxFileSize + 4096: MaxBodySize is the largest request body: a config of MaxFileSize bytes is a JSON string in it, where every newline, quote and tab takes two bytes and a control character six, so the body of a maximal valid config is up to six times the file.
  • const MaxFileSize = 1 << 20: MaxFileSize is the largest config the editor reads, and the largest request body it accepts.
  • const ModeLine: ModeLine is what the editor says wherever it shows a verdict: the check is the structural one bide check makes.
  • const TokenHeader = "X-Bide-Token": TokenHeader is the request header that carries the session token on every /api call.

Functions

  • func Listen(addr string) (net.Listener, error): Listen listens on addr, which must name a loopback IP or localhost, as bide view does.
  • func RemovedComments(old, new []byte) []string: RemovedComments lists the lines the diff from old to new removes that are comments: a line whose first non-blank character is "#" (YAML), and the trailing comment of a removed or changed line.
  • func ToJSON(data []byte) ([]byte, error): ToJSON converts a YAML flow config to the JSON plan reads, as bide check does: the document is decoded into plain values (a duplicate key is an error, as plan's strict JSON reading refuses one), every mapping key must be a string, and a second document is an error rather than ignored.
  • func UnifiedDiff(name string, old, new []byte) string: UnifiedDiff is the plain unified diff that turns old into new, the bytes the editor would write over the file shown as diff -u shows them ("--- a/name", "+++ b/name", hunks), or "" when the two are the same.
  • func Verify(old, out []byte, op Op) (err error): Verify checks that out is old with op applied and nothing else: the data, the key order, the lines outside the operated entry, and which entry each comment belongs to.

type Applied ​

go
type Applied struct {
	Text    []byte
	Changed bool

	Cascade []string
}

Applied is the result of an operation: the new text and whether it differs from the old.

Constructors and functions

  • func ApplyOperation(name string, src []byte, op Operation) (*Applied, error): ApplyOperation applies op to the config text src, which is YAML or JSON as name's extension says.

type Approval ​

go
type Approval struct {
	Need             int      `json:"need"`
	Approvers        []string `json:"approvers"`
	ExcludePrincipal bool     `json:"exclude_principal"`
	Timeout          string   `json:"timeout,omitempty"`
}

Approval is a node's approval gate as the config writes it: Need decisions from the Approvers, never counting the run's requester when ExcludePrincipal is set, and a deadline (a Go duration such as "48h", "" for none).

type Arm ​

go
type Arm struct {
	Pred    string `json:"pred"`
	To      string `json:"to"`
	LoopMax int    `json:"loop_max,omitempty"`
}

Arm is one arm of a switch; LoopMax is above 0 for a loop-back arm.

type Assertion ​

go
type Assertion struct {
	Form string `json:"form"`
	Node string `json:"node,omitempty"`
	Via  string `json:"via,omitempty"`

	K         int  `json:"k,omitempty"`
	N         int  `json:"n,omitempty"`
	Excluding bool `json:"excluding,omitempty"`
}

Assertion is one line of a config's assert list as the editor builds it: one of the six forms of the grammar plan reads (docs/guides/plan-flows.md, "Policy assertions"), with its parameters.

Constructors and functions

  • func ParseAssertion(line string) (a Assertion, ok bool): ParseAssertion reads a line of the assert list as one of the six forms, in the order plan tries them (a line that is two of them is the first); ok is false for a line that is none, which the check reports and the page shows without a form.

Methods

  • func (a Assertion) Text() (string, error): Text is the assertion as one line of the assert list, or a refusal when its parameters do not make one.

type Conflict ​

go
type Conflict struct {
	Hash string
	Diff string
}

Conflict is the error of a save over a file that changed on disk since the page read it.

Methods

  • func (c *Conflict) Error() string: Error says the file changed on disk and was not overwritten.

type Doc ​

go
type Doc struct {
	View

	Hash string `json:"hash"`
}

Doc is the config file as the server read it.

type Edited ​

go
type Edited struct {
	View
	Changed bool `json:"changed"`

	Cascade []string `json:"cascade,omitempty"`

	Renames []Rename `json:"renames,omitempty"`
}

Edited is the answer to an operation: the View of the new text, and whether the operation changed the text (one that sets a value to what it already is does not).

type KV ​

go
type KV struct {
	Key string
	Val any
}

KV is one entry of a Map.

type Kind ​

go
type Kind int

Kind is the kind of an Operation.

Constants

  • const Set Kind: Set replaces the scalar at Path, or adds the key when Path names a missing map key.
  • const Insert Kind: Insert adds Value at Index of the sequence at Path, or, when Path names a map, adds the key Key with Value.
  • const Delete Kind: Delete removes the map entry or sequence item at Path.
  • const Swap Kind: Swap exchanges the items Index and Index+1 of the sequence at Path.

type Map ​

go
type Map []KV

Map is an ordered map value.

type NeedsConfirmation ​

go
type NeedsConfirmation struct{ Items []string }

NeedsConfirmation is the error of a save of a weakened text that did not carry the confirmation of exactly the items the server computed for it.

Methods

  • func (n *NeedsConfirmation) Error() string: Error lists the items the save needs confirmed.

type Node ​

go
type Node struct {
	Name  string `json:"name"`
	Kind  string `json:"kind"`
	Block string `json:"block,omitempty"`

	Safety string `json:"safety,omitempty"`
	Risk   string `json:"risk,omitempty"`

	Gate string `json:"gate,omitempty"`

	Approval *Approval `json:"approval,omitempty"`

	Problems []string `json:"problems,omitempty"`

	Taint *taintNode `json:"taint,omitempty"`

	In  string `json:"in,omitempty"`
	Out string `json:"out,omitempty"`
}

Node is one declared node as the outline lists it.

type Op ​

go
type Op struct {
	Kind  Kind
	Path  []any
	Index int
	Key   string
	Value any
}

Op is one operation.

type Operation ​

go
type Operation struct {
	Op string `json:"op"`

	Node string `json:"node"`

	Value string `json:"value,omitempty"`

	Approval *Approval `json:"approval,omitempty"`

	Assertion *Assertion `json:"assertion,omitempty"`
	Index     int        `json:"index,omitempty"`

	Pred string `json:"pred,omitempty"`
	To   string `json:"to,omitempty"`

	Inputs []string `json:"inputs,omitempty"`
	Max    int      `json:"max,omitempty"`

	DryRun  bool     `json:"dry_run,omitempty"`
	Confirm []string `json:"confirm,omitempty"`
}

Operation is one edit the page asks for, in the closed vocabulary of docs/design/visual-editor.md ("Operations").

type Option ​

go
type Option func(*options)

Option configures New.

Constructors and functions

  • func WithBase(rev string) Option: WithBase compares edits with the file at the git revision rev (a branch, tag or commit, as git show rev:./file takes it) instead of at HEAD.
  • func WithBlocks(d plan.RegistryDescription) Option: WithBlocks makes the editor typed against a description of the program's registrations (plan.Registry.Describe, read from a file by bide edit -blocks).
  • func WithDefaultTheme(name string) Option: WithDefaultTheme sets the theme the page starts in, by name: a shipped theme or one added with WithThemes.
  • func WithRegistry(reg *plan.Registry) Option: WithRegistry makes the editor typed against the program's Registry: it checks the config as Load does (block, predicate and merge names, the types along every edge, safety, the gates the blocks declare in Go, the digest), lists the blocks in a palette, and refuses an operation that connects what does not fit.
  • func WithTaintPolicy(p agent.TaintPolicy) Option: WithTaintPolicy gives a typed editor (WithRegistry or WithBlocks) the taint policy of the flow its program runs, which a Registry does not hold (it is Builder.WithTaintPolicy), and which overrides a description's own.
  • func WithThemeLock(name string) Option: WithThemeLock makes the named theme the only one the page has: the page's switch is hidden, a remembered choice is ignored, and the reader's system setting no longer picks light or dark; a reader who asks their system for more contrast or forced colors still gets those, over the lock.
  • func WithThemes(themes ...*theme.Theme) Option: WithThemes adds custom themes, each from theme.Parse or theme.Load (so each passed the checks in docs/design/themes.md), beside the shipped light, dark and high-contrast.

type PaletteBlock ​

go
type PaletteBlock struct {
	Name string `json:"name"`

	Kind   string   `json:"kind"`
	In     string   `json:"in,omitempty"`
	Inputs []string `json:"inputs,omitempty"`
	Out    string   `json:"out"`

	Safety string `json:"safety"`
	Gate   string `json:"gate,omitempty"`

	Used bool `json:"used"`
}

PaletteBlock is one registered block or merge as the palette shows it.

type Preview ​

go
type Preview struct {
	Diff string `json:"diff"`

	RemovedComments []string `json:"removed_comments,omitempty"`

	Changed bool `json:"changed"`

	Hash     string `json:"hash"`
	Conflict bool   `json:"conflict,omitempty"`

	NeedsConfirmation []string `json:"needs_confirmation,omitempty"`

	NeedsKinds []string `json:"needs_kinds,omitempty"`

	Errors   int `json:"errors"`
	Warnings int `json:"warnings"`
}

Preview is what the editor shows before it writes: the plain unified diff of the bytes it would write against the file on disk now, the comments that diff removes, what the save needs the author to confirm, and whether the file changed on disk since the page read it.

type Refusal ​

go
type Refusal struct{ Reason string }

Refusal is why the engine would not apply an operation.

Methods

  • func (r *Refusal) Error() string: Error describes the refusal, starting with "flowedit: refused:".

type Rename ​

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

Rename is one rename the author made in this editing session: the node From became To.

type Result ​

go
type Result struct {
	Text   []byte
	Lo, Hi int
	Frag   []byte
}

Result is an applied operation: the new text and the byte range of the original it replaced.

Constructors and functions

  • func Apply(src []byte, op Op) (*Result, error): Apply applies op to src.

type Server ​

go
type Server struct {
	// contains filtered or unexported fields
}

Server is the editor for one config file.

Constructors and functions

  • func New(path string, opts ...Option) (*Server, error): New returns the editor for the file at path.

Methods

  • func (s *Server) BaselineNote() string: BaselineNote is "" when the baseline is what it should be, and otherwise says why git HEAD was not used although the file may be in a repository; bide edit prints it at startup.
  • func (s *Server) Close() error: Close releases the directory handle.
  • func (s *Server) Doc() (*Doc, error): Doc reads the file and returns its View with the hash of the bytes read.
  • func (s *Server) Handler() http.Handler: Handler serves the editor: the page at /, its files under /assets/, and the API under /api/.
  • func (s *Server) Preview(text []byte, hash string) (*Preview, error): Preview describes saving text over the file whose bytes the page read as hash.
  • func (s *Server) Save(text []byte, hash string, confirmed []string) (*Doc, error): Save writes text over the file, if and only if: the file on disk is still the bytes the page read (hash), the text is a config the editor will write (at most MaxFileSize bytes, no NUL), and, when the text is weaker than the baseline or could not be compared, confirmed is exactly the list Preview named.
  • func (s *Server) Token() string: Token is the session token the page sends in TokenHeader.

type Stat ​

go
type Stat struct {
	Value string `json:"value"`
	Label string `json:"label"`
	Sub   string `json:"sub,omitempty"`
	Class string `json:"class,omitempty"`
}

Stat is one key number under the verdict.

type TypedView ​

go
type TypedView struct {
	Source string `json:"source"`
	Label  string `json:"label"`

	Digest string `json:"digest,omitempty"`

	Palette []PaletteBlock `json:"palette"`
}

TypedView is what typed mode adds to a View: what the check rests on, the digest, and the blocks the program offers.

type Verdict ​

go
type Verdict struct {
	Class   string   `json:"class"`
	Word    string   `json:"word"`
	Icon    string   `json:"icon"`
	Line    string   `json:"line"`
	Details []string `json:"details,omitempty"`
	Stats   []Stat   `json:"stats,omitempty"`
}

Verdict is the banner the page opens with: Class (good, bad, warn, info), the state in capitals with a glyph name, and a line of why.

type View ​

go
type View struct {
	Name   string `json:"name"`
	Format string `json:"format"`

	Text string `json:"text"`

	Mode string `json:"mode"`

	ParseError string `json:"parse_error,omitempty"`

	Flow  string `json:"flow,omitempty"`
	Entry string `json:"entry,omitempty"`

	In  string `json:"in,omitempty"`
	Out string `json:"out,omitempty"`

	Verdict    Verdict                `json:"verdict"`
	Errors     int                    `json:"errors"`
	Warnings   int                    `json:"warnings"`
	Problems   []plan.ConfigProblem   `json:"problems,omitempty"`
	Assertions []plan.AssertionResult `json:"assertions,omitempty"`

	AssertionForms []*Assertion `json:"assertion_forms,omitempty"`

	Nodes  []Node   `json:"nodes,omitempty"`
	Wiring []string `json:"wiring,omitempty"`

	Wires []Wire `json:"wires,omitempty"`

	Graph string `json:"graph,omitempty"`

	Weakening *Weakening `json:"weakening,omitempty"`

	Typed *TypedView `json:"typed,omitempty"`

	Taint *taintSummary `json:"taint,omitempty"`
}

View is what the editor page shows of one version of the config text: the same answers bide check and bide view -config give for it, computed in Go.

Constructors and functions

  • func BuildView(name string, text []byte) *View: BuildView is the View of text, the contents of the file called name.

type Weakening ​

go
type Weakening struct {
	Baseline string `json:"baseline"`

	Weakened []string `json:"weakened,omitempty"`

	Word string `json:"word,omitempty"`
	Line string `json:"line,omitempty"`

	Strengthened []string `json:"strengthened,omitempty"`

	Changes []string `json:"changes,omitempty"`

	Renamed []string `json:"renamed,omitempty"`

	CompareError string `json:"compare_error,omitempty"`

	NotCertified string `json:"not_certified,omitempty"`
}

Weakening is the answer to "is this text a weaker flow than the one we started from": the classifier bide check -diff runs (runview.BuildDiff), on the text and the baseline.

Constructors and functions

  • func Compare(name, source string, baseline, text []byte) *Weakening: Compare classifies text against baseline, both the contents of a config file called name.
  • func CompareRenamed(name, source string, baseline, text []byte, renames []Rename) *Weakening: CompareRenamed is Compare for a text reached by the renames given, in order: the baseline is read as it would be had those renames been made in it, so a renamed node is matched to its baseline self instead of reading as a removed node and a new one.

type Wire ​

go
type Wire struct {
	Kind   string   `json:"kind"`
	From   string   `json:"from,omitempty"`
	To     string   `json:"to,omitempty"`
	Over   string   `json:"over,omitempty"`
	Arms   []Arm    `json:"arms,omitempty"`
	Else   string   `json:"else,omitempty"`
	Join   string   `json:"join,omitempty"`
	Inputs []string `json:"inputs,omitempty"`
	Merge  string   `json:"merge,omitempty"`
}

Wire is one element of the config's wiring as the page edits it: an edge (From, To), a switch (Over, its Arms and Else) or a join (Join, Inputs, Merge).

Apache-2.0 licensed.