graph

type Artifact struct {
	Path          string // absolute path
	Stem          string // filename stem (README for modules, <id> otherwise)
	Module        string // owning module id, derived from placement
	CollectionDir string // "entities"/"relationships"/... or "" for a module README

	// Raw frontmatter presence — a key being present (even if empty) matters
	// for several rules (owner, fields/properties, sources, lifecycle).
	HasFrontmatter bool
	FMError        string

	// Decoded scalar fields.
	Kind    string
	ID      string
	Name    string
	Status  string
	Summary string

	// module
	DependsOn []string

	// entity
	Model                  string
	LifecycleStates        []string
	LifecycleStatesPresent bool

	// relationship. From/To always carry the endpoint reference; FromRole/
	// ToRole carry the optional decision-0012 role labels of the map form.
	From        string
	FromRole    string
	To          string
	ToRole      string
	Cardinality string
	Metadata    []MetaEntry

	// command / event. Participants carries the references (scalar view);
	// ParticipantItems carries the role-labeled per-item view (decision 0012).
	Subject          string
	Actors           []string
	Participants     []string
	ParticipantItems []ParticipantItem
	Inputs           []InputItem

	PossibleEvents []string
	Sources        []string

	// RoleIssues collects endpoint/participant shape violations (decision
	// 0012) for the graph-role-labels rule.
	RoleIssues []RoleIssue

	// Rules carries the Tier-1 rules: list of entity/relationship/command
	// artifacts (decision 0013); rulesMalformed records a non-list container
	// or non-map items, mirroring the inputs pattern.
	Rules []RuleItem

	// policy (decision 0013). AppliesKind/AppliesRef are set when the applies:
	// block carries exactly one of command|entity|relationship; the raw clause
	// structures back the graph-policy-shape rule.
	AppliesKind string
	AppliesRef  string
	// contains filtered or unexported fields
}

type Concept struct {
	Name       string
	Kind       string // "entity", "component", "enum", "collection", or "recordset"
	File       string // absolute path to the .hcl file
	Line       int
	EnumValues []string // populated for enum concepts only
	Properties []string // property/field member names (entity/component concepts; decision 0013 actor-is.model-role)
}

type Graph struct {
	Root     string   // absolute repo-level graph root (may not exist)
	Roots    []string // absolute paths of every existing graph root in the union
	RepoRoot string   // absolute repo root (contains specscore.yaml)
	Modules  []*Module
}

type InputItem struct {
	Name      string
	Ref       string
	Model     string
	HasName   bool
	HasRef    bool
	HasModel  bool
	ExtraKeys []string
	Line      int
}

type LintOptions struct {
	RepoRoot string   // absolute repo root (contains specscore.yaml)
	Root     string   // graph-root override relative to RepoRoot; "" = spec/graph
	Rules    []string // enabled rules; nil = all
	Ignore   []string // disabled rules
	Severity string   // minimum severity: error|warning|info; "" = no filter
	Fix      bool     // when true, apply the specified graph fixers on disk
}

type LintResult struct {
	Violations  []lint.Violation
	NoGraphRoot bool
	Fixed       []string
}

type ListItem struct {
	ID    string `json:"id" yaml:"id"`
	Kind  string `json:"kind" yaml:"kind"`
	Name  string `json:"name" yaml:"name"`
	Owner string `json:"owner" yaml:"owner"`
	Path  string `json:"path" yaml:"path"`
}

type MetaEntry struct {
	Key    string
	Value  string // scalar text when Scalar is true
	Scalar bool
	Line   int
}

type ModelDiag struct {
	File    string
	Line    int
	Message string
}

type ModelModule struct {
	ID          string
	Dir         string
	Concepts    []*Concept
	Refs        []*ModelRef
	ParseErrors []ModelDiag
}

type ModelRef struct {
	Target string
	Attr   string // "entity", "component", "enum", or "use"
	Owner  string // declaring concept name
	File   string
	Line   int
}

type ModelspecParseError struct {
	Rewrite string
	// contains filtered or unexported fields
}

type ModelspecRef struct {
	Module   string
	Kind     string // singular: entity|component|enum|collection|recordset; "" = two-segment (trio)
	Name     string
	Repo     string // "{host}/{org}/{repo}" for cross-repo, or "" for local
	Ref      string // advisory ?ref= git pin (branch/tag/commit), or ""
	Fragment string // '#<value>' enum-value address (decision 0013), or ""
}

type Module struct {
	ID        string
	Root      string      // absolute path to the module directory
	Readme    *Artifact   // parsed README.md frontmatter, or nil when absent
	DependsOn []string    // declared outbound dependencies (from README)
	Artifacts []*Artifact // collection artifacts owned by this module
	ModelDir  string      // absolute path to models/, or "" when absent
	Model     *ModelModule
}

type ParticipantItem struct {
	Ref  string
	Role string
	Line int
}

type QualifiedRef struct {
	Module string
	Local  string
}

type RefItem struct {
	ID   string `json:"id" yaml:"id"`
	Kind string `json:"kind" yaml:"kind"`
	Path string `json:"path" yaml:"path"`
}

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

type RoleIssue struct {
	Line    int
	Message string
}

type RuleItem struct {
	ID        string
	Text      string
	Refs      []string
	HasID     bool
	HasText   bool
	ExtraKeys []string
	Line      int
	// contains filtered or unexported fields
}

type ScaffoldOptions struct {
	Kind     string
	Name     string
	ID       string // optional; derived from Name when empty
	Module   string // required for non-module kinds
	RepoRoot string // absolute repo root
	Root     string // repo-level graph-root override (relative); "" = spec/graph
	Status   string // default "draft"
	Summary  string
	From     string // relationship
	To       string // relationship
	Subject  string // command / event
	Bare     bool   // module: skip collection scaffolding
}

type ScaffoldResult struct {
	Created []string
	Target  string
}