projectdef

README

pkg/projectdef

specscore.yaml schema and read/write operations per the Repo Config feature. Validates the mandatory schema-header comment on line 1, applies SpecStudio defaults for viewer:, and enforces module path uniqueness/non-nesting.

Outstanding Questions

None at this time.

Documentation

Overview

Package projectdef provides the specscore.yaml schema and read/write operations defined by the SpecScore Repo Config feature (https://specscore.md/repo-config).

Index

• Constants
• func IsValidRole(r Role) bool
• func ValidateSchemaHeader(data []byte) error
• func WriteSpecConfig(dir string, cfg SpecConfig) error
• type ModuleConfig
  • func (m ModuleConfig) EffectiveName() string
  • func (m ModuleConfig) EffectivePath() string
• type ProjectConfig
• type RepositoryConfig
  • func (r *RepositoryConfig) UnmarshalYAML(node *yaml.Node) error
• type Role
• type SpecConfig
  • func ReadSpecConfig(dir string) (SpecConfig, error)
  • func (c SpecConfig) EffectiveDocsDirName() string
  • func (c SpecConfig) EffectiveModules() []ModuleConfig
  • func (c SpecConfig) EffectiveSpecsDirName() string
  • func (c SpecConfig) EffectiveStudio() (name, url string, suppressed bool)
  • func (c SpecConfig) IsStudioSuppressed() bool
  • func (c SpecConfig) Validate() error
• type StudioConfig

Constants

const (
	DefaultSpecsDirName = "specs"
	DefaultDocsDirName  = "docs"
	DefaultStudioName   = "SpecScore.Studio"
	DefaultStudioURL    = "https://specscore.studio/"
	DefaultModuleName   = "default"
)

Default values supplied when fields are omitted.

const SchemaHeader = "# SpecScore Repo Config Schema: https://specscore.md/repo-config"

SchemaHeader is the exact comment that MUST appear on line 1 of every specscore.yaml file. See repo-config#req:schema-header-comment.

const SpecConfigFile = "specscore.yaml"

SpecConfigFile is the canonical filename for the repo-level config, per the repo-config feature.

Functions

func IsValidRole

func IsValidRole(r Role) bool

IsValidRole reports whether r is a member of the canonical role enum.

func ValidateSchemaHeader

func ValidateSchemaHeader(data []byte) error

ValidateSchemaHeader verifies the first line of `data` is exactly the schema-header comment. Returns nil on success.

func WriteSpecConfig

func WriteSpecConfig(dir string, cfg SpecConfig) error

WriteSpecConfig serializes cfg to dir/specscore.yaml, prepending the schema-header comment as line 1.

Types

type ModuleConfig

type ModuleConfig struct {
	Name   string         `yaml:"name,omitempty"`
	Path   string         `yaml:"path,omitempty"`
	Code   []string       `yaml:"code,omitempty"`
	Extras map[string]any `yaml:",inline"`
}

ModuleConfig is one entry in the `modules:` list — a code area inside the repo, optionally with its own specs/docs subdirectories.

func (ModuleConfig) EffectiveName

func (m ModuleConfig) EffectiveName() string

EffectiveName returns the module's effective name per repo-config#req:module-name-deduction.

func (ModuleConfig) EffectivePath

func (m ModuleConfig) EffectivePath() string

EffectivePath returns the module's effective filesystem path, defaulting to "." (repo root) when no path is set.

type ProjectConfig

type ProjectConfig struct {
	Title        string             `yaml:"title,omitempty"`
	Host         string             `yaml:"host,omitempty"`
	Org          string             `yaml:"org,omitempty"`
	Repo         string             `yaml:"repo,omitempty"`
	Repositories []RepositoryConfig `yaml:"repositories,omitempty"`
	Extras       map[string]any     `yaml:",inline"`
}

ProjectConfig holds project identity. All fields are optional; when omitted, callers infer values from the working directory and git remote.

type RepositoryConfig

type RepositoryConfig struct {
	URL     string         `yaml:"url"`
	Title   string         `yaml:"title,omitempty"`
	Comment string         `yaml:"comment,omitempty"`
	Roles   []Role         `yaml:"roles"`
	Extras  map[string]any `yaml:",inline"`
}

RepositoryConfig is one entry in `project.repositories`. Per repo-config#req:repositories-entry-shape every entry MUST be a YAML mapping (object) with a non-empty `roles` list — flat URL strings are rejected.

func (*RepositoryConfig) UnmarshalYAML

func (r *RepositoryConfig) UnmarshalYAML(node *yaml.Node) error

UnmarshalYAML enforces repo-config#req:repositories-entry-shape — the entry MUST be a mapping (not a scalar / not a sequence). Flat URL strings are rejected with a hard error citing the violated REQ.

type Role

type Role string

Role is a value from the closed enum defined in repo-config#req:repositories-roles-enum.

const (
	RoleCode          Role = "code"
	RoleSpecification Role = "specification"
	RoleState         Role = "state"
	RoleDocs          Role = "docs"
	RoleRunner        Role = "runner"
)

Canonical role values per repo-config#req:repositories-roles-enum. The enum is closed in v1; new values require a Feature revision.

type SpecConfig

type SpecConfig struct {
	Project      *ProjectConfig `yaml:"project,omitempty"`
	Projects     []string       `yaml:"projects,omitempty"`
	SpecsDirName string         `yaml:"specs_dir_name,omitempty"`
	DocsDirName  string         `yaml:"docs_dir_name,omitempty"`
	Studio       *StudioConfig  `yaml:"studio,omitempty"`
	Modules      []ModuleConfig `yaml:"modules,omitempty"`
	Extras       map[string]any `yaml:",inline"`
	// contains filtered or unexported fields
}

SpecConfig is the deserialized form of specscore.yaml.

func ReadSpecConfig

func ReadSpecConfig(dir string) (SpecConfig, error)

ReadSpecConfig reads dir/specscore.yaml and decodes it. The file must begin with the schema-header comment on line 1; otherwise an error is returned without further parsing.

The pre-2026-05-19 `viewer:` block is rejected with a migration error (repo-config#req:viewer-block-rejected). It MUST be hand-renamed to `studio:` — there is no auto-migration in this pre-v1 break.

func (SpecConfig) EffectiveDocsDirName

func (c SpecConfig) EffectiveDocsDirName() string

EffectiveDocsDirName returns the configured docs dir name or the default.

func (SpecConfig) EffectiveModules

func (c SpecConfig) EffectiveModules() []ModuleConfig

EffectiveModules returns the module list with the implicit-root default applied per repo-config#req:modules-default.

func (SpecConfig) EffectiveSpecsDirName

func (c SpecConfig) EffectiveSpecsDirName() string

EffectiveSpecsDirName returns the configured specs dir name or the default.

func (SpecConfig) EffectiveStudio

func (c SpecConfig) EffectiveStudio() (name, url string, suppressed bool)

EffectiveStudio reports the studio to use for artifact links. suppressed is true when `studio: null` was set explicitly — callers MUST omit any toolbar in that case (repo-config#req:studio-null-opts-out). When the block is omitted entirely, name and url default to SpecScore.Studio (repo-config#req:studio-default-when-omitted).

func (SpecConfig) IsStudioSuppressed

func (c SpecConfig) IsStudioSuppressed() bool

IsStudioSuppressed reports whether studio: null was set in the source.

func (SpecConfig) Validate

func (c SpecConfig) Validate() error

Validate checks the structural invariants that don't require I/O: studio mapping completeness, repositories entry shape and role-enum membership, and module path uniqueness/non-nesting. File-system checks (e.g. projects local-path resolution) belong to the linter.

type StudioConfig

type StudioConfig struct {
	Name string `yaml:"name"`
	URL  string `yaml:"url"`
}

StudioConfig names the upstream studio that renders SpecScore artifacts. Both fields are required when the block is present. Replaces the pre-2026-05-19 `viewer:` block (repo-config#req:studio-explicit-values).