package engine

import "github.com/O6lvl4/gformiac/engine"

Package engine implements the core logic for gformiac: schema types, state management, Google Forms API interactions, diff computation, and validation.

Index

Functions

func NewFormSummary

func NewFormSummary(spec *FormSpec) string

NewFormSummary returns a human-readable plan for creating a new form.

func SaveSpec

func SaveSpec(path string, spec *FormSpec) error

SaveSpec writes a FormSpec as YAML to the given path.

func SaveState

func SaveState(path string, state *State) error

SaveState writes the state to disk as formatted JSON. It creates parent directories if they do not exist.

func ValidChoiceTypes

func ValidChoiceTypes() string

ValidChoiceTypes returns the recognized choice types as a display string.

func ValidItemTypes

func ValidItemTypes() string

ValidItemTypes returns the recognized item types as a display string.

func Validate

func Validate(spec *FormSpec) error

Validate checks a FormSpec against Google Forms API constraints. It returns a *ValidationError containing all failures, or nil if the spec is valid.

Types

type Change

type Change struct {
	Type  ChangeType
	Index int
	Old   *ItemSpec
	New   *ItemSpec
}

Change represents a single item-level difference.

type ChangeType

type ChangeType int

ChangeType classifies a diff entry. 

const (
	// ChangeCreate indicates an item exists locally but not remotely.
	ChangeCreate ChangeType = iota
	// ChangeUpdate indicates an item exists in both places but differs.
	ChangeUpdate
	// ChangeDelete indicates an item exists remotely but not locally.
	ChangeDelete
)

Change type constants used to categorize item-level differences.

func (ChangeType) String
func (t ChangeType) String() string

String returns a label for the change type.

type ChoiceSpec

type ChoiceSpec struct {
	Type    ChoiceType `yaml:"type"`
	Options []string   `yaml:"options"`
}

ChoiceSpec defines the options for a choice question.

type ChoiceType

type ChoiceType string

ChoiceType represents the sub-type of a choice question. 

const (
	// ChoiceRadio renders options as radio buttons (single-select).
	ChoiceRadio ChoiceType = "radio"
	// ChoiceCheckbox renders options as checkboxes (multi-select).
	ChoiceCheckbox ChoiceType = "checkbox"
	// ChoiceDropdown renders options as a dropdown list (single-select).
	ChoiceDropdown ChoiceType = "dropdown"
)

Recognized choice sub-types for ItemChoice questions.

func (ChoiceType) IsValid
func (t ChoiceType) IsValid() bool

IsValid reports whether t is a recognized choice type.

type Client

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

Client wraps the Google Forms API service.

func NewClient
func NewClient(ctx context.Context, credentialsFile, tokenFile string) (*Client, error)

NewClient creates an authenticated Forms API client. It first attempts Application Default Credentials (ADC) and falls back to interactive OAuth2 using the provided credentials and token files.

func (*Client) CreateForm
func (c *Client) CreateForm(ctx context.Context, spec *FormSpec) (*State, error)

CreateForm creates a new Google Form from the spec and returns the resulting state.

func (*Client) ImportForm
func (c *Client) ImportForm(ctx context.Context, formID string) (*FormSpec, *State, error)

ImportForm fetches a remote form and converts it to a FormSpec and State.

func (*Client) Plan
func (c *Client) Plan(ctx context.Context, formID string, spec *FormSpec, state *State) (*DiffResult, error)

Plan fetches the remote form and computes the diff against the local spec.

func (*Client) UpdateForm
func (c *Client) UpdateForm(ctx context.Context, formID string, spec *FormSpec) (*State, error)

UpdateForm reconciles the remote form to match the local spec.

type DiffResult

type DiffResult struct {
	InfoChanged bool
	InfoDetails []string
	Changes     []Change
}

DiffResult holds the full set of differences between local and remote forms.

func Diff
func Diff(local, remote *FormSpec, _ *State) *DiffResult

Diff computes the differences between a local spec and a remote spec. The State parameter is reserved for future use (e.g., ID-based matching).

func (*DiffResult) HasChanges
func (d *DiffResult) HasChanges() bool

HasChanges reports whether there are any differences.

func (*DiffResult) String
func (d *DiffResult) String() string

String formats the diff as a human-readable summary.

type FormSpec

type FormSpec struct {
	Title       string     `yaml:"title"`
	Description string     `yaml:"description,omitempty"`
	Items       []ItemSpec `yaml:"items"`
}

FormSpec is the top-level YAML definition of a Google Form.

func LoadSpec
func LoadSpec(path string) (*FormSpec, error)

LoadSpec reads and parses a YAML form definition file.

type ItemSpec

type ItemSpec struct {
	Title       string      `yaml:"title"`
	Description string      `yaml:"description,omitempty"`
	Type        ItemType    `yaml:"type"`
	Required    bool        `yaml:"required,omitempty"`
	Choice      *ChoiceSpec `yaml:"choice,omitempty"`
	Scale       *ScaleSpec  `yaml:"scale,omitempty"`
}

ItemSpec defines a single item (question, page break, etc.) in a form.

type ItemType

type ItemType string

ItemType represents the type of a form item. 

const (
	// ItemShortAnswer is a single-line text question.
	ItemShortAnswer ItemType = "short_answer"
	// ItemParagraph is a multi-line text question.
	ItemParagraph ItemType = "paragraph"
	// ItemChoice is a question with selectable options (radio, checkbox, or dropdown).
	ItemChoice ItemType = "choice"
	// ItemScale is a linear-scale question with a numeric range.
	ItemScale ItemType = "scale"
	// ItemDate is a date-picker question.
	ItemDate ItemType = "date"
	// ItemTime is a time-picker question.
	ItemTime ItemType = "time"
	// ItemPageBreak inserts a visual page break between sections.
	ItemPageBreak ItemType = "page_break"
)

Recognized item types that map directly to Google Forms question types.

func (ItemType) IsValid
func (t ItemType) IsValid() bool

IsValid reports whether t is a recognized item type.

type ScaleSpec

type ScaleSpec struct {
	Low       int64  `yaml:"low"`
	High      int64  `yaml:"high"`
	LowLabel  string `yaml:"low_label,omitempty"`
	HighLabel string `yaml:"high_label,omitempty"`
}

ScaleSpec defines the range and labels for a linear scale question.

type State

type State struct {
	FormID       string    `json:"form_id"`
	ResponderURL string    `json:"responder_url,omitempty"`
	ItemIDs      []string  `json:"item_ids"`
	QuestionIDs  []string  `json:"question_ids"`
	LastApplied  time.Time `json:"last_applied"`
}

State tracks the mapping between a local form definition and its remote Google Form.

func LoadState
func LoadState(path string) (*State, error)

LoadState reads the state file. Returns (nil, nil) if the file does not exist, signaling that no form has been created yet.

type ValidationError

type ValidationError struct {
	Errors []string
}

ValidationError collects multiple validation failures into a single error.

func (*ValidationError) Error
func (e *ValidationError) Error() string

Error implements the error interface and returns a summary of all collected validation failures.