prelviz

README

prelviz

A visualization tool for self custom package relation by creating dot format file. This tool help you to understand self custom package relation and maintain project architecture.

※ above image is the result of using prelviz to testdata/sample_project without config.

Install

You can get prelviz by go install command.

$ go install github.com/kazdevl/prelviz/cmd/prelviz@v1.1.0

NOTE: you need go 1.21 or later.

How to use

$ prelviz -i {{project directory path}}

$ prelviz -i {{project directory path}} -l {{dot layout}}

$ prelviz -i {{project directory path}} -o {{output file path}}

$ prelviz -i {{project directory path}} | dot -Tsvg -o sample.svg

NOTE: if you want to exec above usage, you need to install graphviz.

Use with config

If you want to use prelviz with config, you need to create .prelviz.config.json in project directory path. .prelviz.config.json have four fields, ng_relation, grouping_grouping_directory_path, exclude_package and exclude_directory_path.

example)

{
  "ng_relation": [
    {
      "from": "github.com/kazdevl/sample_project/app/usecase",
      "to": ["github.com/kazdevl/sample_project/app/domain"]
    }
  ],
  "grouping_directory_path": ["app/domain"],
  "exclude_package": [
    "github.com/kazdevl/sample_project/app/util",
    "github.com/kazdevl/sample_project/app/domain/entity"
  ],
  "exclude_directory_path": ["github.com/kazdevl/sample_project/app/exclude"]
}

You can set from and to value in ng_relation when you want to detect dependencies that violate the project's architecture. When you set from and to value, you have to set package path. If prelviz detects architecture violation, the color of edges between the target packages turns red.

example)

You can set grouping_directory_path when you want to group packages in the result image of prelviz. When you set grouping_directory_path value, you have to set directory path.

example)

You can set exclude_package when you want to exclude packages in the result image of prelviz. When you set exclude_package value, you have to set package path.

example)

You can set exclude_directory_path when you want to exclude packages in target directoies in the result image of prelviz. When you set exclude_directory_path value, you have to set directory path.

Point

The values in grouping_directory_path are treated as package, so it must also be considered when setting ng_relation.

example)

the sample go project

• module name: github.com/kazdevl/sample_project
• package list
  • github.com/kazdevl/sample_project/app/usecase
  • github.com/kazdevl/sample_project/app/domain/service
  • github.com/kazdevl/sample_project/app/domain/repository
  • github.com/kazdevl/sample_project/app/domain/entity
  • github.com/kazdevl/sample_project/app/domain/model
• directory path

.
└── app
    ├── domain
    |   ├── service
    |   |   ├── sample1.go
    |   |   └── sample2.go
    |   ├── repository
    |   |   ├── sample1.go
    |   |   └── sample2.go
    |   ├── entity
    |   |   ├── sample1.go
    |   |   └── sample2.go
    |   └── model
    |       ├── sample1.go
    |       └── sample2.go
    └── usecase
        ├── sample1.go
        └── sample2.go

• config before setting grouping_directory_path

{
  "ng_relation": [
    {
      "from": "github.com/kazdevl/sample_project/app/usecase",
      "to": ["github.com/kazdevl/sample_project/app/domain/model"]
    }
  ]
}

In the above situation, when setting the grouping_directory_path, you need to modify the config as follows

{
  "ng_relation": [
    {
      "from": "github.com/kazdevl/sample_project/app/usecase",
      "to": ["github.com/kazdevl/sample_project/app/domain"]
    }
  ],
  "grouping_directory_path": ["app/domain"]
}

to value is github.com/kazdevl/sample_project/app/domain, not github.com/kazdevl/sample_project/app/domain/model.

Recomendation

If you try to use prelviz to the go project that have a lot of packages, it is recommended to set grouping_directory_path and exclude_directory_path in .prelviz.config.json. Otherwise, when the output is converted to an image, the number of elements is too large and visibility is catastrophic.

Flags

  -i string
        requreid: "true", description: "input project directory path"
  -l string
        requreid: "false", description: "dot layout. ex) dot, neato, fdp, sfdp, twopi, circo" (default "dot")
  -o string
        requreid: "false", description: "output file path(default is stdout)"

Prelviz Image Description

• color of node indicates node type
  • blue: package
  • green: directory
• color of edge indicates dependency type
  • white: default
  • red: architecture violation
• pkg in blue node indicates package name
• pkg in green node indicates the number of packages under the node
• path in blue node indicates directory path that package exists
• path in green node indicates directory path
• dep on edge indicates number of dependencies on structures, functions, etc. of the package to which the arrow points

Example

The result of using prelviz to pipecd with the following .prelviz.config.json settings.

{
    "grouping_directory_path": [
        "examples",
        "pkg/admin",
        "pkg/app/helloworld",
        "pkg/app/launcher",
        "pkg/app/ops",
        "pkg/app/pipectl",
        "pkg/app/piped",
        "pkg/app/server",
        "pkg/cache",
        "pkg/cli",
        "pkg/config",
        "pkg/crypto",
        "pkg/datastore",
        "pkg/diff",
        "pkg/filestore",
        "pkg/git",
        "pkg/insight",
        "pkg/jwt",
        "pkg/log",
        "pkg/redis",
        "pkg/rpc",
        "test/integration",
        "tool"
    ]
}

dot layout is dot

dot layout is circo

Contributing

Welcome to contribute to this project.

Fork and make a Pull Request, or create an Issue if you see any problem or any enhancement, feature request.

Documentation

Index

• func GetModuleName(rootPath string) (string, error)
• func NewPackageInfoMap(projectDirectoryPath string) (map[string]*PackageInfo, error)
• type Config
  • func NewConfig(path, moduleName string) (*Config, error)
  • func (c *Config) GroupingPackageDirectoryPath(pkgDirPath string) string
  • func (c *Config) IsExcludePackage(pkg string) bool
  • func (c *Config) IsGroupingPackage(pkgDirPath string) bool
  • func (c *Config) IsNgRelation(from string, to string) bool
• type ConfigBinder
  • func (c ConfigBinder) ToConfig(path, moduleName string) (*Config, error)
• type NgRelation
• type NodeInfo
• type PackageInfo
  • func NewPackageInfo(filePath, projectDirectoryPath string) (*PackageInfo, error)
• type PackageInfoMap
• type Prelviz
  • func NewPrelviz(projectDirectoryPath, outputFilePath, dotLayout string) (*Prelviz, error)
  • func (m *Prelviz) Run() error

Functions

func GetModuleName

func GetModuleName(rootPath string) (string, error)

func NewPackageInfoMap

func NewPackageInfoMap(projectDirectoryPath string) (map[string]*PackageInfo, error)

Types

type Config

type Config struct {
	NgRelationMap          map[string]map[string]struct{}
	GroupingDirectoryPaths []string
	ExcludePackageMap      map[string]struct{}
}

func NewConfig

func NewConfig(path, moduleName string) (*Config, error)

func (*Config) GroupingPackageDirectoryPath

func (c *Config) GroupingPackageDirectoryPath(pkgDirPath string) string

func (*Config) IsExcludePackage

func (c *Config) IsExcludePackage(pkg string) bool

func (*Config) IsGroupingPackage

func (c *Config) IsGroupingPackage(pkgDirPath string) bool

func (*Config) IsNgRelation

func (c *Config) IsNgRelation(from string, to string) bool

type ConfigBinder

type ConfigBinder struct {
	NgRelations            []NgRelation `json:"ng_relation"`
	GroupingDirectoryPaths []string     `json:"grouping_directory_path"`
	ExcludePackages        []string     `json:"exclude_package"`
	ExcludeDirectoryPaths  []string     `json:"exclude_directory_path"`
}

func (ConfigBinder) ToConfig

func (c ConfigBinder) ToConfig(path, moduleName string) (*Config, error)

type NgRelation

type NgRelation struct {
	From string   `json:"from"`
	To   []string `json:"to"`
}

type NodeInfo

type NodeInfo struct {
	Name               string
	DirectoryPath      string
	IsGrouping         bool
	ContainsPackageNum int
}

type PackageInfo

type PackageInfo struct {
	Name           string
	DirectoryPath  string
	ImportUsageMap map[string]map[string]struct{}
}

func NewPackageInfo

func NewPackageInfo(filePath, projectDirectoryPath string) (*PackageInfo, error)

type PackageInfoMap

type PackageInfoMap map[string]*PackageInfo

type Prelviz

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

func NewPrelviz

func NewPrelviz(projectDirectoryPath, outputFilePath, dotLayout string) (*Prelviz, error)

func (*Prelviz) Run

func (m *Prelviz) Run() error