feat: read catalog component tags from README front-matter

Author: yhakbar

docs/src/content/docs/03-features/06-catalog/02-tui.mdx

@@ -7,6 +7,8 @@ sidebar:
 ---
 
 import { Aside } from '@astrojs/starlight/components';
+import Since from '@components/Since.astro';
+import Before from '@components/Before.astro';
 
 Launch the user interface for searching and managing your module catalog.
 
@@ -102,3 +104,86 @@ This section describes behavior that is only available when the [`catalog-redesi
 </Aside>
 
 The list view is split into three tabs: `All`, `Modules`, and `Templates`. `All` is selected when the TUI launches. Press `tab` to move to the next tab and `shift+tab` to move to the previous; cycling wraps at either end. The active tab filters the list down to components of that kind, and each tab keeps its own cursor position and search filter, so switching back preserves where you were.
+
+## README front-matter
+
+<Aside type="tip" title="Catalog Redesign Experiment">
+This section describes behavior that is only available when the [`catalog-redesign`](/reference/experiments/active#catalog-redesign) experiment is enabled.
+</Aside>
+
+Component authors can override the catalog UI's default title and description by adding a YAML block at the top of the component's `README.md`. Two forms are accepted.
+
+The conventional dash-separated form:
+
+```markdown
+---
+name: VPC App
+description: A VPC for application workloads.
+---
+
+# VPC App
+
+...
+```
+
+An HTML-comment-wrapped form, which stays invisible on Markdown viewers that render dash-separated front-matter as a horizontal rule. The opening tag must be `<!-- Frontmatter` (case-insensitive):
+
+```markdown
+<!-- Frontmatter
+name: VPC App
+description: A VPC for application workloads.
+-->
+
+# VPC App
+
+...
+```
+
+Both forms are parsed the same way.
+
+Recognized keys:
+
+- `name`: the component title shown in the list view. When unset, the title falls back to the first `# H1` heading in the README, then to the directory name.
+- `description`: the short description shown beneath the title in the list view. When unset, it is derived from the README body.
+
+A third key, `tags`, controls the colored pills shown next to each component; see the next section. Unknown keys are ignored.
+
+## Component tags
+
+<Aside type="tip" title="Catalog Redesign Experiment">
+This section describes behavior that is only available when the [`catalog-redesign`](/reference/experiments/active#catalog-redesign) experiment is enabled.
+</Aside>
+
+<Before version="1.0.4">
+
+In a future release, the catalog UI will read tag information from the front-matter of component `README.md` files.
+
+</Before>
+
+<Since version="1.0.4">
+
+Catalog authors can attach tags to a component by adding a `tags` key to the component's `README.md` front-matter. Tags appear as colored pills next to the component in the list view, and as a row above the rendered README in the detail view.
+
+Either inline-array or dash-list YAML form is accepted:
+
+```markdown
+<!-- Frontmatter
+name: VPC App
+description: A VPC for application workloads.
+tags: [networking, aws, module]
+-->
+```
+
+```markdown
+<!-- Frontmatter
+name: VPC App
+tags:
+  - networking
+  - aws
+  - module
+-->
+```
+
+Tag values that name a component type also promote the component into that type's tab. For example, a component classified as a `template` whose tags include `module` appears under both the `Templates` tab (by its native kind) and the `Modules` tab (by tag), without changing how it's scaffolded.
+
+</Since>

docs/src/data/changelog/v1.0.4/catalog-tags.mdx

@@ -0,0 +1,22 @@
+---
+version: "v1.0.4"
+category: "experiments-updated"
+---
+
+#### `catalog-redesign`: component tags
+
+The `catalog-redesign` experiment now reads a `tags` field from the component's `README.md` front-matter. Tags appear as colored pills next to the component in the list view and in the detail view above the rendered README.
+
+```markdown
+<!-- Frontmatter
+name: VPC App
+description: A VPC for application workloads.
+tags: [networking, aws, module]
+-->
+```
+
+Either inline-array or dash-list YAML form is accepted. Tags render in gray by default. When a tag matches a known component-type name (`module`, `template`, `unit`, or `stack`, case-insensitive), the pill takes on that type's color.
+
+A tag matching a component-type name also promotes the component into that type's tab. A `template` whose tags include `module` appears under both `Templates` (by its native kind) and `Modules` (by tag), without changing how it scaffolds.
+
+To learn more, see [Component tags](/features/catalog/tui#component-tags).

go.mod

@@ -102,6 +102,7 @@ require (
 	github.com/xeipuuv/gojsonschema v1.2.0
 	go.uber.org/mock v0.6.0
 	golang.org/x/exp v0.0.0-20260312153236-7ab1446f8b90
+	gopkg.in/yaml.v3 v3.0.1
 )
 
 require (
@@ -305,7 +306,6 @@ require (
 	google.golang.org/genproto v0.0.0-20260406210006-6f92a3bedf2d // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20260406210006-6f92a3bedf2d // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260406210006-6f92a3bedf2d // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
 	sigs.k8s.io/yaml v1.6.0 // indirect
 )
 

internal/cli/commands/catalog/tui/redesign/component.go

@@ -110,6 +110,16 @@ func (c *Component) Description() string {
 // FilterValue is what the list fuzzy-matches against when the user filters.
 func (c *Component) FilterValue() string { return c.Title() }
 
+// Tags returns the component's README front-matter tags, in authoring order.
+// Returns nil when the component has no Doc or declares no tags.
+func (c *Component) Tags() []string {
+	if c.Doc == nil {
+		return nil
+	}
+
+	return c.Doc.Tags()
+}
+
 // URL returns the browser-friendly source URL for the component, or an empty
 // string if one could not be derived.
 func (c *Component) URL() string { return c.url }

internal/cli/commands/catalog/tui/redesign/component_doc.go

@@ -5,6 +5,8 @@ import (
 	"regexp"
 	"strings"
 
+	"gopkg.in/yaml.v3"
+
 	"github.com/gruntwork-io/terragrunt/internal/errors"
 	"github.com/gruntwork-io/terragrunt/internal/vfs"
 )
@@ -27,11 +29,6 @@ const (
 
 var (
 	docFiles = []string{"README.md", "README.adoc"}
-
-	frontmatterKeys = map[string]docDataKey{
-		"name":        docTitle,
-		"description": docDescription,
-	}
 )
 
 type docDataKey byte
@@ -49,13 +46,17 @@ func (regs docRegs) Replace(str string) string {
 
 // ComponentDoc is the parsed README (Markdown or AsciiDoc) for a Component.
 type ComponentDoc struct {
-	tagCache         map[docDataKey]string
-	tagRegs          map[docTagName]*regexp.Regexp
-	frontmatterCache map[docDataKey]string
-	frontmatterReg   *regexp.Regexp
-	rawContent       string
-	fileExt          string
-	tagStripRegs     docRegs
+	tagCache           map[docDataKey]string
+	tagRegs            map[docTagName]*regexp.Regexp
+	frontmatterCache   map[docDataKey]string
+	frontmatterTags    []string
+	frontmatterReg     *regexp.Regexp
+	frontmatterDashReg *regexp.Regexp
+	frontmatterBody    string
+	rawContent         string
+	fileExt            string
+	tagStripRegs       docRegs
+	frontmatterDone    bool
 }
 
 // NewComponentDoc builds a ComponentDoc from raw README content.
@@ -64,10 +65,13 @@ func NewComponentDoc(rawContent, fileExt string) *ComponentDoc {
 		rawContent: rawContent,
 		fileExt:    fileExt,
 
-		tagRegs:        make(map[docTagName]*regexp.Regexp),
-		frontmatterReg: regexp.MustCompile(`(?i)^[\s\n]*<!-- frontmatter[\s\n]*([\S\s]*?)[\s\n]*-->`),
+		tagRegs:            make(map[docTagName]*regexp.Regexp),
+		frontmatterReg:     regexp.MustCompile(`(?i)^[\s\n]*<!-- frontmatter[\s\n]*([\S\s]*?)[\s\n]*-->`),
+		frontmatterDashReg: regexp.MustCompile(`(?m)\A[\s\n]*---[\s\n]+([\S\s]*?)[\s\n]+---(?:[\s\n]|$)`),
 	}
 
+	doc.extractFrontmatter()
+
 	switch fileExt {
 	case mdExt:
 		doc.tagRegs[tagH1Block] = regexp.MustCompile(`(?:^|\n)\#{1}\s([\S\s]+?)(?:[\r\n]+\#|[\r\n]*$)`)
@@ -164,6 +168,22 @@ func (doc *ComponentDoc) Title() string {
 	return doc.parseTag(docTitle)
 }
 
+// Tags returns the list of tags declared in the README front-matter, in
+// authoring order. Returns nil when no tags are defined or no front-matter
+// is present.
+func (doc *ComponentDoc) Tags() []string {
+	doc.ensureFrontmatter()
+
+	if len(doc.frontmatterTags) == 0 {
+		return nil
+	}
+
+	out := make([]string, len(doc.frontmatterTags))
+	copy(out, doc.frontmatterTags)
+
+	return out
+}
+
 // Description returns a short description, optionally capped at maxLength.
 func (doc *ComponentDoc) Description(maxLength int) string {
 	desc := doc.parseFrontmatter(docDescription)
@@ -215,36 +235,104 @@ func (doc *ComponentDoc) IsMarkDown() bool {
 }
 
 func (doc *ComponentDoc) parseFrontmatter(key docDataKey) string {
-	if doc.frontmatterReg == nil {
-		return ""
+	doc.ensureFrontmatter()
+
+	return doc.frontmatterCache[key]
+}
+
+// ensureFrontmatter parses the README front-matter block as YAML on first
+// use, populating frontmatterCache (name/description) and frontmatterTags.
+//
+// Unknown keys and parse errors are silently ignored.
+func (doc *ComponentDoc) ensureFrontmatter() {
+	if doc.frontmatterDone {
+		return
+	}
+
+	doc.frontmatterDone = true
+	doc.frontmatterCache = make(map[docDataKey]string)
+
+	if doc.frontmatterBody == "" {
+		return
+	}
+
+	var raw map[string]any
+	if err := yaml.Unmarshal([]byte(doc.frontmatterBody), &raw); err != nil || raw == nil {
+		return
 	}
 
-	if doc.frontmatterCache == nil {
-		doc.frontmatterCache = make(map[docDataKey]string)
+	for k, v := range raw {
+		switch strings.ToLower(strings.TrimSpace(k)) {
+		case "name":
+			if s, ok := v.(string); ok {
+				doc.frontmatterCache[docTitle] = strings.TrimSpace(s)
+			}
+		case "description":
+			if s, ok := v.(string); ok {
+				doc.frontmatterCache[docDescription] = strings.TrimSpace(s)
+			}
+		case "tags":
+			doc.frontmatterTags = coerceTags(v)
+		}
+	}
+}
 
-		match := doc.frontmatterReg.FindStringSubmatch(doc.rawContent)
-		if len(match) == 0 {
-			return ""
+// extractFrontmatter captures the YAML body of the README's front-matter
+// block (if any) and removes the matched block from rawContent so downstream
+// rendering (glamour, tag-stripping) does not treat the front-matter as part
+// of the README body. Either the dash-separated form (`---\n...\n---`) or
+// the HTML-comment-wrapped form (`<!-- Frontmatter ... -->`) is accepted.
+func (doc *ComponentDoc) extractFrontmatter() {
+	for _, reg := range []*regexp.Regexp{doc.frontmatterDashReg, doc.frontmatterReg} {
+		if reg == nil {
+			continue
 		}
 
-		lines := strings.SplitSeq(match[1], "\n")
+		loc := reg.FindStringSubmatchIndex(doc.rawContent)
+		if len(loc) == 0 {
+			continue
+		}
+
+		doc.frontmatterBody = doc.rawContent[loc[2]:loc[3]]
+		doc.rawContent = strings.TrimLeft(doc.rawContent[loc[1]:], "\r\n")
+
+		return
+	}
+}
+
+// coerceTags accepts the YAML-decoded value of the `tags` key and returns a
+// trimmed, non-empty slice of strings. It accepts either a sequence
+// (`["a","b"]` or a `- a` block) or a single string.
+func coerceTags(v any) []string {
+	switch val := v.(type) {
+	case []any:
+		out := make([]string, 0, len(val))
 
-		for line := range lines {
-			rawKey, rawVal, ok := strings.Cut(line, ":")
+		for _, item := range val {
+			s, ok := item.(string)
 			if !ok {
 				continue
 			}
 
-			key := strings.ToLower(strings.TrimSpace(rawKey))
-			val := strings.TrimSpace(rawVal)
-
-			if key, ok := frontmatterKeys[key]; ok {
-				doc.frontmatterCache[key] = val
+			s = strings.TrimSpace(s)
+			if s == "" {
+				continue
 			}
+
+			out = append(out, s)
+		}
+
+		return out
+	case string:
+		s := strings.TrimSpace(val)
+		if s == "" {
+			return nil
 		}
+
+		return []string{s}
 	}
 
-	return doc.frontmatterCache[key]
+	return nil
 }
 
 func (doc *ComponentDoc) parseTag(key docDataKey) string {