Merge pull request #839 from k1LoW/out-viewpoint

feat: add viewpoint id and tbls out --viewpoint

Author: k1LoW

README.md

@@ -1097,6 +1097,7 @@ You can also define groups of tables within viewpoints.
 
 viewpoints:
   -
+    id: comments-on-post
     name: comments on post
     desc: Users can comment on each post multiple times and put a star on each comment.
     tables:
@@ -1123,6 +1124,8 @@ viewpoints:
 
 ```
 
+`id` is optional. When set, it is used as the suffix of the viewpoint output file name (e.g. `viewpoint-comments-on-post.md`) instead of the index, so the file name stays stable regardless of the viewpoint order. `id` must be unique and must not contain path separators (`/` or `\`). It is also used to specify the viewpoint in `tbls out --viewpoint`.
+
 ## Output formats
 
 `tbls out` output in various formats.
@@ -1157,6 +1160,20 @@ $ tbls out -t mermaid -o schema.mmd
 $ tbls out -t svg --table users --distance 2 -o users.svg
 ```
 
+**Viewpoint:**
+
+Output only the schema of a specific viewpoint by specifying its `id` (or index).
+
+```console
+$ tbls out -t svg --viewpoint comments-on-post -o comments-on-post.svg
+```
+
+With `-t md`, the viewpoint document (including groups and the ER diagram inlined as Mermaid) is generated instead of a plain schema document.
+
+```console
+$ tbls out -t md --viewpoint comments-on-post -o comments-on-post.md
+```
+
 **JSON:**
 
 ```console

cmd/out.go

@@ -38,13 +38,15 @@ import (
 	"github.com/k1LoW/tbls/output/plantuml"
 	"github.com/k1LoW/tbls/output/xlsx"
 	"github.com/k1LoW/tbls/output/yaml"
+	"github.com/k1LoW/tbls/schema"
 	"github.com/spf13/cobra"
 )
 
 var (
-	format   string
-	outPath  string
-	distance int
+	format    string
+	outPath   string
+	distance  int
+	viewpoint string
 )
 
 // outCmd represents the doc command.
@@ -79,6 +81,18 @@ var outCmd = &cobra.Command{
 			return err
 		}
 
+		var vp *schema.Viewpoint
+		var vpIndex int
+		if viewpoint != "" {
+			v, i, err := s.FindViewpoint(viewpoint)
+			if err != nil {
+				return err
+			}
+			vp = v
+			vpIndex = i
+			s = v.Schema
+		}
+
 		var o output.Output
 
 		switch format {
@@ -124,6 +138,18 @@ var outCmd = &cobra.Command{
 			wr = os.Stdout
 		}
 
+		// For Markdown, output the dedicated viewpoint document (ER + groups) instead of
+		// the plain filtered schema. The ER diagram is inlined as Mermaid so the single
+		// output file stays self-contained without a separate image file.
+		if vp != nil && format == "md" {
+			c.ER.Skip = false
+			c.ER.Format = "mermaid"
+			if err := md.New(c).OutputViewpoint(wr, vpIndex, vp); err != nil {
+				return err
+			}
+			return nil
+		}
+
 		if err := o.OutputSchema(wr, s); err != nil {
 			return err
 		}
@@ -167,5 +193,6 @@ func init() {
 	outCmd.Flags().StringSliceVarP(&excludes, "exclude", "", []string{}, "tables to exclude")
 	outCmd.Flags().StringSliceVarP(&labels, "label", "", []string{}, "table labels to be included")
 	outCmd.Flags().IntVarP(&distance, "distance", "", 0, "distance between related tables to be displayed")
+	outCmd.Flags().StringVarP(&viewpoint, "viewpoint", "", "", "output only the specified viewpoint (by id, or by index); with -t md the viewpoint document (groups + ER) is generated")
 	outCmd.Flags().StringVarP(&when, "when", "", "", "command execute condition")
 }

config/config.go

@@ -322,13 +322,34 @@ func (c *Config) validate() error {
 	if !lo.Contains(SupportERFormat, c.ER.Format) {
 		return fmt.Errorf("unsupported ER format: %s", c.ER.Format)
 	}
+	seenViewpointIDs := map[string]int{}
+	seenViewpointNames := map[string]int{}
 	for i, v := range c.Viewpoints {
 		if v.Name == "" {
 			return fmt.Errorf("viewpoints[%d] name is required", i)
 		}
 		if v.Desc == "" {
 			return fmt.Errorf("viewpoints[%d] description is required", i)
 		}
+		if v.ID != "" {
+			// id is embedded into output file paths (e.g. viewpoint-<id>.md), so path
+			// separators would allow writing outside the intended output directory.
+			if strings.ContainsAny(v.ID, `/\`) {
+				return fmt.Errorf("viewpoints[%d] id '%s' must not contain path separators ('/' or '\\')", i, v.ID)
+			}
+			if j, ok := seenViewpointIDs[v.ID]; ok {
+				return fmt.Errorf("viewpoints[%d] id '%s' is duplicated with viewpoints[%d]", i, v.ID, j)
+			}
+			seenViewpointIDs[v.ID] = i
+		}
+		// An id-based name and an index-based name can collide (e.g. viewpoints[0] without id
+		// produces viewpoint-0, and viewpoints[1] with id "0" produces viewpoint-0 too), which
+		// would silently overwrite output files. Reject such conflicts on the derived name.
+		name := schema.ViewpointName(v.ID, i)
+		if j, ok := seenViewpointNames[name]; ok {
+			return fmt.Errorf("viewpoints[%d] output name '%s' conflicts with viewpoints[%d]", i, name, j)
+		}
+		seenViewpointNames[name] = i
 		for j, g := range v.Groups {
 			if g.Name == "" {
 				return fmt.Errorf("viewpoints[%d].groups[%d] name is required", i, j)
@@ -492,6 +513,7 @@ func (c *Config) ModifySchema(s *schema.Schema) error {
 			tables = left
 		}
 		s.Viewpoints = s.Viewpoints.Merge(&schema.Viewpoint{
+			ID:       v.ID,
 			Name:     v.Name,
 			Desc:     v.Desc,
 			Labels:   v.Labels,
@@ -528,6 +550,7 @@ func (c *Config) ModifySchema(s *schema.Schema) error {
 			for _, tt := range ts {
 				tt.Viewpoints = append(tt.Viewpoints, &schema.TableViewpoint{
 					Index: vi,
+					ID:    v.ID,
 					Name:  v.Name,
 					Desc:  v.Desc,
 				})

config/config_test.go

@@ -596,6 +596,84 @@ func TestValidate(t *testing.T) {
 	}
 }
 
+func TestValidateViewpointID(t *testing.T) {
+	tests := []struct {
+		name       string
+		viewpoints []Viewpoint
+		wantErr    bool
+	}{
+		{"no id", []Viewpoint{{Name: "A", Desc: "a"}, {Name: "B", Desc: "b"}}, false},
+		{"unique ids", []Viewpoint{{ID: "a", Name: "A", Desc: "a"}, {ID: "b", Name: "B", Desc: "b"}}, false},
+		{"empty ids are not duplicated", []Viewpoint{{Name: "A", Desc: "a"}, {Name: "B", Desc: "b"}, {Name: "C", Desc: "c"}}, false},
+		{"duplicated ids", []Viewpoint{{ID: "a", Name: "A", Desc: "a"}, {ID: "a", Name: "B", Desc: "b"}}, true},
+		{"id with slash", []Viewpoint{{ID: "../../pwned", Name: "A", Desc: "a"}}, true},
+		{"id with backslash", []Viewpoint{{ID: `a\b`, Name: "A", Desc: "a"}}, true},
+		{"id with nested slash", []Viewpoint{{ID: "a/b", Name: "A", Desc: "a"}}, true},
+		{"id collides with index-based name", []Viewpoint{{Name: "A", Desc: "a"}, {ID: "0", Name: "B", Desc: "b"}}, true},
+		{"id matching own index is fine", []Viewpoint{{ID: "0", Name: "A", Desc: "a"}, {Name: "B", Desc: "b"}}, false},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			c, err := New()
+			if err != nil {
+				t.Fatal(err)
+			}
+			c.Viewpoints = tt.viewpoints
+			if err := c.validate(); err != nil {
+				if !tt.wantErr {
+					t.Errorf("got error: %s", err)
+				}
+				return
+			}
+			if tt.wantErr {
+				t.Error("want error")
+			}
+		})
+	}
+}
+
+func TestModifySchemaViewpointID(t *testing.T) {
+	c, err := New()
+	if err != nil {
+		t.Fatal(err)
+	}
+	c.Viewpoints = []Viewpoint{
+		{ID: "users-overview", Name: "Users", Desc: "users overview", Tables: []string{"users"}},
+		{Name: "Posts", Desc: "posts", Tables: []string{"posts"}},
+	}
+	s := newTestSchemaViaJSON(t)
+	if err := c.ModifySchema(s); err != nil {
+		t.Fatal(err)
+	}
+
+	// ID is propagated to schema viewpoint.
+	if got := s.Viewpoints[0].ID; got != "users-overview" {
+		t.Errorf("viewpoint[0].ID = %q, want %q", got, "users-overview")
+	}
+	if got := s.Viewpoints[1].ID; got != "" {
+		t.Errorf("viewpoint[1].ID = %q, want empty", got)
+	}
+
+	// ID is propagated to table viewpoint.
+	tb, err := s.FindTableByName("users")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var found bool
+	for _, tv := range tb.Viewpoints {
+		if tv.Name != "Users" {
+			continue
+		}
+		found = true
+		if tv.ID != "users-overview" {
+			t.Errorf("table viewpoint ID = %q, want %q", tv.ID, "users-overview")
+		}
+	}
+	if !found {
+		t.Error("users table viewpoint 'Users' not found")
+	}
+}
+
 func TestCheckVersion(t *testing.T) {
 	tests := []struct {
 		v    string

config/viewpoints.go

@@ -1,6 +1,7 @@
 package config
 
 type Viewpoint struct {
+	ID       string           `yaml:"id,omitempty"`
 	Name     string           `yaml:"name,omitempty"`
 	Desc     string           `yaml:"desc,omitempty"`
 	Labels   []string         `yaml:"labels,omitempty"`

output/gviz/gviz.go

@@ -142,7 +142,7 @@ func Output(s *schema.Schema, c *config.Config, force bool) (e error) {
 
 	// viewpoints
 	for i, v := range s.Viewpoints {
-		fn := fmt.Sprintf("viewpoint-%d.%s", i, erFormat)
+		fn := fmt.Sprintf("%s.%s", schema.ViewpointName(v.ID, i), erFormat)
 		fmt.Printf("%s\n", filepath.Join(outputPath, fn))
 		f, err := os.OpenFile(filepath.Join(fullPath, fn), os.O_WRONLY|os.O_CREATE|os.O_TRUNC, 0644) // #nosec
 		if err != nil {
@@ -227,8 +227,8 @@ func outputErExists(s *schema.Schema, erFormat, path string) bool {
 		}
 	}
 	// viewpoints
-	for i := range s.Viewpoints {
-		fn := fmt.Sprintf("viewpoint-%d.%s", i, erFormat)
+	for i, v := range s.Viewpoints {
+		fn := fmt.Sprintf("%s.%s", schema.ViewpointName(v.ID, i), erFormat)
 		if _, err := os.Lstat(filepath.Join(path, fn)); err == nil {
 			return true
 		}

output/md/md.go

@@ -122,7 +122,7 @@ func (m *Md) OutputViewpoint(wr io.Writer, i int, v *schema.Viewpoint) error {
 		}
 		templateData["erDiagram"] = fmt.Sprintf("```mermaid\n%s```", buf.String())
 	default:
-		templateData["erDiagram"] = fmt.Sprintf("![er](%sviewpoint-%d.%s)", m.config.BaseURL, i, m.config.ER.Format)
+		templateData["erDiagram"] = fmt.Sprintf("![er](%s%s.%s)", m.config.BaseURL, mdurl.Encode(schema.ViewpointName(v.ID, i)), m.config.ER.Format)
 	}
 	if err := tmpl.Execute(wr, templateData); err != nil {
 		return errors.WithStack(err)
@@ -184,7 +184,7 @@ func Output(s *schema.Schema, c *config.Config, force bool) (e error) {
 
 	// viewpoints
 	for i, v := range s.Viewpoints {
-		fn := fmt.Sprintf("viewpoint-%d.md", i)
+		fn := fmt.Sprintf("%s.md", schema.ViewpointName(v.ID, i))
 		f, err := os.Create(filepath.Clean(filepath.Join(fullPath, fn)))
 		if err != nil {
 			_ = f.Close()
@@ -393,8 +393,8 @@ func DiffSchemaAndDocs(docPath string, s *schema.Schema, c *config.Config) (stri
 	// viewpoints
 	for i, v := range s.Viewpoints {
 		buf := new(bytes.Buffer)
-		n := fmt.Sprintf("viewpoint-%d", i)
-		fn := fmt.Sprintf("viewpoint-%d.md", i)
+		n := schema.ViewpointName(v.ID, i)
+		fn := fmt.Sprintf("%s.md", n)
 		to := fmt.Sprintf("%s %s", mdsn, n)
 		if err := md.OutputViewpoint(buf, i, v); err != nil {
 			return "", errors.WithStack(err)
@@ -609,7 +609,7 @@ func (m *Md) makeTableTemplateData(t *schema.Table) map[string]interface{} {
 			desc = output.ShowOnlyFirstParagraph(desc)
 		}
 		data := []string{
-			fmt.Sprintf("[%s](viewpoint-%d.md)", v.Name, v.Index),
+			fmt.Sprintf("[%s](%s.md)", v.Name, mdurl.Encode(schema.ViewpointName(v.ID, v.Index))),
 			desc,
 		}
 
@@ -925,7 +925,7 @@ func (m *Md) viewpointsData(viewpoints []*schema.Viewpoint, number, adjust, show
 			desc = output.ShowOnlyFirstParagraph(desc)
 		}
 		d := []string{
-			fmt.Sprintf("[%s](%sviewpoint-%d.md)", v.Name, m.config.BaseURL, i),
+			fmt.Sprintf("[%s](%s%s.md)", v.Name, m.config.BaseURL, mdurl.Encode(schema.ViewpointName(v.ID, i))),
 			desc,
 		}
 		data = append(data, d)

schema/schema.go

@@ -5,6 +5,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"sort"
+	"strconv"
 	"strings"
 
 	wildcard "github.com/IGLOU-EU/go-wildcard/v2"
@@ -52,6 +53,7 @@ func (labels Labels) Contains(name string) bool {
 
 // Viewpoint is the struct for viewpoint information.
 type Viewpoint struct {
+	ID       string            `json:"id,omitempty"`
 	Name     string            `json:"name"`
 	Desc     string            `json:"desc"`
 	Labels   []string          `json:"labels,omitempty"`
@@ -82,6 +84,31 @@ func (vs Viewpoints) Merge(in *Viewpoint) Viewpoints {
 	return append(vs, in)
 }
 
+// ViewpointName returns the basename (without extension) used for the viewpoint output file.
+// When id is set it is used to keep the name stable regardless of viewpoint order, otherwise the index is used.
+// Config validation rejects ids with path separators, but schemas loaded directly (e.g. json://) bypass it,
+// so fall back to the index-based name to keep the result safe to embed in file paths.
+func ViewpointName(id string, index int) string {
+	if id != "" && !strings.ContainsAny(id, `/\`) {
+		return fmt.Sprintf("viewpoint-%s", id)
+	}
+	return fmt.Sprintf("viewpoint-%d", index)
+}
+
+// FindViewpoint finds a viewpoint by id, falling back to index when locator is a number.
+// It also returns the index of the viewpoint.
+func (s *Schema) FindViewpoint(locator string) (*Viewpoint, int, error) {
+	for i, v := range s.Viewpoints {
+		if v.ID != "" && v.ID == locator {
+			return v, i, nil
+		}
+	}
+	if index, err := strconv.Atoi(locator); err == nil && index >= 0 && index < len(s.Viewpoints) {
+		return s.Viewpoints[index], index, nil
+	}
+	return nil, 0, fmt.Errorf("viewpoint not found: %s", locator)
+}
+
 // Index is the struct for database index.
 type Index struct {
 	Name    string   `json:"name"`
@@ -130,6 +157,7 @@ type Column struct {
 
 type TableViewpoint struct {
 	Index int    `json:"index"`
+	ID    string `json:"id,omitempty"`
 	Name  string `json:"name"`
 	Desc  string `json:"desc"`
 }