scriptflow

type Edge struct {
	From string `json:"from"`
	To   string `json:"to"`
	// Via names the functions that reshaped the value on the way.
	Via  []string `json:"via"`
	Kind string   `json:"kind" example:"data"`
	// Change is "removed" on an edge of a compared graph that only the older
	// version had.
	Change string `json:"change,omitempty"`
}

type FuncSpan struct {
	Name    string `json:"name"`
	Line    int    `json:"line"`
	EndLine int    `json:"end_line"`
}

type Function struct {
	Name string `json:"name" example:"last_week"`
	// Params is each parameter as the source writes it, a default included.
	Params []string `json:"params" example:"today,days=7"`
	// Doc is the first sentence of the function's docstring.
	Doc  string `json:"doc,omitempty" example:"The seven days before today."`
	Line int    `json:"line" example:"12"`
}

type Graph struct {
	// OK is false when the source does not parse or resolve. Findings then
	// says why, and the diagram is empty.
	OK       bool                `json:"ok"`
	Findings []scriptrun.Finding `json:"findings"`
	Nodes    []Node              `json:"nodes"`
	Edges    []Edge              `json:"edges"`
	Groups   []Group             `json:"groups"`
	Params   []Param             `json:"params"`
	// Lines is the source's line count, for the reader's scale.
	Lines int `json:"lines" example:"136"`
	// Truncated is true when the script expands into more steps than one
	// diagram draws; the graph holds the first ones.
	Truncated bool `json:"truncated"`
	// Structure is the script drawn in the order it runs (#1972), the Flow
	// tab's default view.
	Structure Structure `json:"structure"`
	// ComparedWith is the older version this graph is compared against
	// (#1908), zero when it is not a comparison.
	ComparedWith int `json:"compared_with,omitempty"`
	// Library is present when the script is a library (#1970): the functions
	// it defines for another script to load. Derive does not set it: whether
	// a script is a library is recorded when it is created, and a source with
	// no main() saved before libraries existed is not one, so the caller that
	// holds the script attaches it with LibraryOf.
	Library *Library `json:"library,omitempty"`
}

type Group struct {
	ID      string `json:"id" example:"/load_orders"`
	Label   string `json:"label" example:"load_orders(day)"`
	Caption string `json:"caption,omitempty"`
	// Parent is the id of the enclosing box, empty at the top level.
	Parent     string `json:"parent,omitempty"`
	DefLine    int    `json:"def_line" example:"12"`
	CalledFrom []int  `json:"called_from"`
}

type Library struct {
	// Functions is every function a load can name, in source order.
	Functions []Function `json:"functions"`
	// Load is the statement that loads every one of them from this version,
	// empty when there is none to load.
	Load string `json:"load,omitempty" example:"load(\"lib:date-windows@2\", \"last_week\")"`
}

type Node struct {
	ID   string `json:"id" example:"op:3"`
	Role string `json:"role" example:"reads"`
	Kind string `json:"kind" example:"query"`
	// Title is the action and where it goes; Subtitle the operation, name or
	// path; Purpose the purpose sentence the author wrote on the call.
	Title    string `json:"title" example:"Query warehouse"`
	Subtitle string `json:"subtitle,omitempty"`
	Purpose  string `json:"purpose,omitempty"`
	// Detail is the tables, paths or keys the step touches.
	Detail []string `json:"detail"`
	// Computed is true when what the step reaches is only known at run time;
	// the computed part is written as {its source} in the text above.
	Computed bool `json:"computed"`
	// Group is the id of the function box the step is drawn in, empty at the
	// top level.
	Group string `json:"group,omitempty"`
	// Line and EndLine are the platform call's lines. Site is the line the
	// folded wrapper named in Wrapper is called from.
	Line    int    `json:"line" example:"42"`
	EndLine int    `json:"end_line" example:"44"`
	Site    int    `json:"site,omitempty"`
	Wrapper string `json:"wrapper,omitempty"`
	// Loops are the for statements the step repeats in, outermost first.
	Loops []string `json:"loops"`
	// CallSite is the position of every call on the stack that makes this
	// step's call, outermost first, as "line:col": what a run records on the
	// step's audited calls and outputs (#1907), so a run is drawn on the card
	// that made each call.
	CallSite []string `json:"call_site,omitempty"`
	// Change and Was mark a node of a compared graph (#1908): added, changed
	// (with what it said before) or removed (carried over from the older
	// version).
	Change string `json:"change,omitempty"`
	Was    *Was   `json:"was,omitempty"`
}

type Param struct {
	Name string `json:"name" example:"day"`
	// Line is where the source first reads it.
	Line int `json:"line" example:"3"`
	// Reaches lists the steps whose arguments the parameter's value reaches.
	Reaches []string `json:"reaches"`
	// Decides is true when the value is read by a condition, so it decides
	// which steps run.
	Decides bool `json:"decides"`
}

type StructBox struct {
	ID   string `json:"id" example:"b:2"`
	Kind string `json:"kind" example:"loop"`
	// Label is a loop's header or a function's signature; Caption the
	// function's first comment sentence.
	Label   string `json:"label"`
	Caption string `json:"caption,omitempty"`
	Parent  string `json:"parent,omitempty"`
	Line    int    `json:"line" example:"12"`
	// CallSite is where this expansion of a function was called from, the
	// prefix every call made inside it carries.
	CallSite []string `json:"call_site,omitempty"`
}

type StructEdge struct {
	From  string `json:"from"`
	To    string `json:"to"`
	Label string `json:"label,omitempty" example:"yes"`
}

type StructNode struct {
	ID   string `json:"id" example:"s:3"`
	Kind string `json:"kind" example:"if"`
	// Label is the if's condition and the fail()'s message, as the source
	// writes them.
	Label string `json:"label,omitempty" example:"len(rows) < 1000"`
	// Step is the value graph's node for a platform call.
	Step string `json:"step,omitempty" example:"op:3"`
	// Box is the loop or function box the node is drawn in.
	Box  string `json:"box,omitempty"`
	Line int    `json:"line" example:"42"`
	// CallSite is a platform call's or a fail()'s position on the stack, as
	// a run records it (#1907).
	CallSite []string `json:"call_site,omitempty"`
}

type Structure struct {
	Nodes []StructNode `json:"nodes"`
	Edges []StructEdge `json:"edges"`
	Boxes []StructBox  `json:"boxes"`
	// Functions is every def with its span, so a call site's frames can be
	// named by the function each line is in.
	Functions []FuncSpan `json:"functions"`
	// Truncated is true when the script expands into more nodes than one
	// diagram draws.
	Truncated bool `json:"truncated"`
}

type Was struct {
	Title    string   `json:"title"`
	Subtitle string   `json:"subtitle,omitempty"`
	Purpose  string   `json:"purpose,omitempty"`
	Detail   []string `json:"detail"`
}