{"id":16092277,"url":"https://github.com/alecthomas/go-check-sumtype","last_synced_at":"2025-04-05T01:06:17.170Z","repository":{"id":142257938,"uuid":"612746627","full_name":"alecthomas/go-check-sumtype","owner":"alecthomas","description":"A simple utility for running exhaustiveness checks on Go \"sum types.\"","archived":false,"fork":false,"pushed_at":"2024-10-05T02:37:27.000Z","size":36,"stargazers_count":21,"open_issues_count":4,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-10T16:06:15.203Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alecthomas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-11T21:14:21.000Z","updated_at":"2024-09-24T02:25:45.000Z","dependencies_parsed_at":"2024-10-25T22:41:46.679Z","dependency_job_id":null,"html_url":"https://github.com/alecthomas/go-check-sumtype","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alecthomas%2Fgo-check-sumtype","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alecthomas%2Fgo-check-sumtype/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alecthomas%2Fgo-check-sumtype/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alecthomas%2Fgo-check-sumtype/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alecthomas","download_url":"https://codeload.github.com/alecthomas/go-check-sumtype/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247271528,"owners_count":20911587,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-09T16:06:32.476Z","updated_at":"2025-04-05T01:06:17.144Z","avatar_url":"https://github.com/alecthomas.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"**Note: This is a fork of the great project [go-sumtype](https://github.com/BurntSushi/go-sumtype) by BurntSushi.**\n**The original seems largely unmaintained, and the changes in this fork are backwards incompatible.**\n\n# go-check-sumtype [![CI](https://github.com/alecthomas/go-check-sumtype/actions/workflows/ci.yml/badge.svg)](https://github.com/alecthomas/go-check-sumtype/actions/workflows/ci.yml)\nA simple utility for running exhaustiveness checks on type switch statements.\nExhaustiveness checks are only run on interfaces that are declared to be\n\"sum types.\"\n\nDual-licensed under MIT or the [UNLICENSE](http://unlicense.org).\n\nThis work was inspired by our code at\n[Diffeo](https://diffeo.com).\n\n## Installation\n\n```go\n$ go get github.com/alecthomas/go-check-sumtype\n```\n\nFor usage info, just run the command:\n\n```\n$ go-check-sumtype\n```\n\nTypical usage might look like this:\n\n```\n$ go-check-sumtype $(go list ./... | grep -v vendor)\n```\n\n## Usage\n\n`go-check-sumtype` takes a list of Go package paths or files and looks for sum type\ndeclarations in each package/file provided. Exhaustiveness checks are then\nperformed for each use of a declared sum type in a type switch statement.\nNamely, `go-check-sumtype` will report an error for any type switch statement that\neither lacks a `default` clause or does not account for all possible variants.\n\nDeclarations are provided in comments like so:\n\n```\n//sumtype:decl\ntype MySumType interface { ... }\n```\n\n`MySumType` must be *sealed*. That is, part of its interface definition\ncontains an unexported method.\n\n`go-check-sumtype` will produce an error if any of the above is not true.\n\nFor valid declarations, `go-check-sumtype` will look for all occurrences in which a\nvalue of type `MySumType` participates in a type switch statement. In those\noccurrences, it will attempt to detect whether the type switch is exhaustive\nor not. If it's not, `go-check-sumtype` will report an error. For example, running\n`go-check-sumtype` on this source file:\n\n```go\npackage main\n\n//sumtype:decl\ntype MySumType interface {\n        sealed()\n}\n\ntype VariantA struct{}\n\nfunc (*VariantA) sealed() {}\n\ntype VariantB struct{}\n\nfunc (*VariantB) sealed() {}\n\nfunc main() {\n        switch MySumType(nil).(type) {\n        case *VariantA:\n        }\n}\n```\n\nproduces the following:\n\n```\n$ sumtype mysumtype.go\nmysumtype.go:18:2: exhaustiveness check failed for sum type 'MySumType': missing cases for VariantB\n```\n\nAdding either a `default` clause or a clause to handle `*VariantB` will cause\nexhaustive checks to pass. To prevent `default` clauses from automatically\npassing checks, set the `-default-signifies-exhasutive=false` flag.\n\nAs a special case, if the type switch statement contains a `default` clause\nthat always panics, then exhaustiveness checks are still performed.\n\nBy default, `go-check-sumtype` will not include shared interfaces in the exhaustiviness check.\nThis can be changed by setting the `-include-shared-interfaces=true` flag.\nWhen this flag is set, `go-check-sumtype` will not require that all concrete structs\nare listed in the switch statement, as long as the switch statement is exhaustive\nwith respect to interfaces the structs implement.\n\n## Details and motivation\n\nSum types are otherwise known as discriminated unions. That is, a sum type is\na finite set of disjoint values. In type systems that support sum types, the\nlanguage will guarantee that if one has a sum type `T`, then its value must\nbe one of its variants.\n\nGo's type system does not support sum types. A typical proxy for representing\nsum types in Go is to use an interface with an unexported method and define\neach variant of the sum type in the same package to satisfy said interface.\nThis guarantees that the set of types that satisfy the interface is closed\nat compile time. Performing case analysis on these types is then done with\na type switch statement, e.g., `switch x.(type) { ... }`. Each clause of the\ntype switch corresponds to a *variant* of the sum type. The downside of this\napproach is that Go's type system is not aware of the set of variants, so it\ncannot tell you whether case analysis over a sum type is complete or not.\n\nThe `go-check-sumtype` command recognizes this pattern, but it needs a small amount\nof help to recognize which interfaces should be treated as sum types, which\nis why the `//sumtype:decl` annotation is required. `go-check-sumtype` will\nfigure out all of the variants of a sum type by finding the set of types\ndefined in the same package that satisfy the interface specified by the\ndeclaration.\n\nThe `go-check-sumtype` command will prove its worth when you need to add a variant\nto an existing sum type. Running `go-check-sumtype` will tell you immediately which\ncase analyses need to be updated to account for the new variant.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falecthomas%2Fgo-check-sumtype","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falecthomas%2Fgo-check-sumtype","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falecthomas%2Fgo-check-sumtype/lists"}