Documentation
¶
Overview ¶
Package frontmatter reads and parses the YAML frontmatter block from spec nodes, test nodes, and external dependency files.
Spec ref: ROOT/tech_design/internal/frontmatter § "Intent"
The frontmatter is the YAML block delimited by the first and second `---` markers at the top of the file. Everything after the second `---` is intentionally ignored — the file body is never read.
Spec ref: ROOT/tech_design/internal/frontmatter § "Parsing"
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DependsOn ¶
type DependsOn struct {
// LogicalName is the logical name of the dependency node (YAML key: "path").
LogicalName string `yaml:"path"`
// Filter holds optional glob patterns for selecting files within an
// external dependency folder (YAML key: "filter").
Filter []string `yaml:"filter"`
}
DependsOn represents a single entry in the `depends_on` frontmatter field.
Spec ref: ROOT/tech_design/internal/frontmatter § "DependsOn structure"
YAML key mapping:
- `path` → LogicalName (logical name of the dependency; required)
- `filter` → Filter (glob patterns for file selection; optional)
type Frontmatter ¶
type Frontmatter struct {
// DependsOn is the list of cross-tree dependencies declared by the node.
// Spec ref: ROOT/tech_design/internal/frontmatter § "DependsOn structure"
DependsOn []DependsOn `yaml:"depends_on"`
// Implements is the list of source file paths generated by this node,
// relative to the project root.
Implements []string `yaml:"implements"`
}
Frontmatter holds the parsed fields extracted from a spec file's YAML frontmatter block.
Spec ref: ROOT/tech_design/internal/frontmatter § "Parsing"
All fields are optional at the parsing level — validation of required fields happens elsewhere. Unknown YAML fields are silently ignored.
Spec ref: EXTERNAL/goccy-go-yaml § "Unmarshal" (unknown fields ignored by default)
func ParseFrontmatter ¶
func ParseFrontmatter(filePath string) (*Frontmatter, error)
ParseFrontmatter reads the file at filePath, extracts the YAML frontmatter block (between the first and second `---` delimiters), and returns the parsed result.
Spec ref: ROOT/tech_design/internal/frontmatter § "Interface"
Efficiency: reads the file line by line and stops immediately after the closing `---` is found. The file body is never read.
Spec ref: ROOT/tech_design/internal/frontmatter § "Efficiency"
ParseFrontmatter does not cache results — caching is the caller's responsibility.
Error messages follow the exact formats mandated by the spec:
- "error reading <path>: <underlying error>"
- "error parsing frontmatter in <path>: <underlying error>"
- "frontmatter not found in <path>"
Spec ref: ROOT/tech_design/internal/frontmatter § "Error handling"
Source Files