Checks recent changes to a Go project for backwards incompatible changes.

# Introduction

[![Build Status](https://travis-ci.org/bradleyfalzon/apicompat.svg?branch=master)](https://travis-ci.org/bradleyfalzon/apicompat) [![Coverage Status](https://coveralls.io/repos/github/bradleyfalzon/apicompat/badge.svg?branch=master)](https://coveralls.io/github/bradleyfalzon/apicompat?branch=master) [![GoDoc](https://godoc.org/github.com/bradleyfalzon/apicompat?status.svg)](https://godoc.org/github.com/bradleyfalzon/apicompat)

`apicompat` is a tool to check for the introduction of backwards incompatible changes.

`apicompat`:
- Guarantees that all consumers of a library will still build without failure
- Only checks exported declarations
- There are no false positives (if there are, it's a bug)
- Not every backwards incompatible change can be detected, swapping argument parameters and other changes still need to
    be considered by the library author
- Can be simply consumed as a library
- Is in its infancy, see [Status](#status), feedback and review appreciated
- Was originally named `abicheck` during early development

Secondary tasks could include:
- Detecting current semver and suggesting an appropriate increase
- Listing all changes for help in writing release notes/commit messages.

Try at [abicheck.bradleyf.id.au](https://abicheck.bradleyf.id.au/) or via CLI:

```
go get -u github.com/bradleyfalzon/apicompat/cmd/apicompat
cd /your/project/dir/with/committed/changes
apicompat
```

# Proposed Arguments

`apicompat` also comes with a command line tool, as well as being used as a library, the following are the proposed flags
and arguments for the command line tool.

```
-vcs    (auto|git|svn|etc) - Version control system to use (default: auto)
-before revision           - Revisions to check as before  (default: if unstaged changes, check those, else check last two commits)
-after  revision           - Revisions to check as after   (default: if unstaged changes, check those, else check last two commits)
-vcsDir path               - Path to root VCS directory    (default: let VCS tool search)
-all                       - Show non-breaking changes as well as breaking (default: false)

apicompat        # current package only
apicompat ./...  # check subdirectory packages
```

Another tool, called `abichanges` may also be included which will list all detected changes to assist in producing
release notes.

# Status

`apicompat` is currently under heavy development and refactoring. This initial version was a proof of concept and shortcuts were taken. The current tasks are focused on (but not limited to):

- Adding Mercurial, SVN and potentially other VCS systems
- Improve VCS options such as:
    - Detection of VCS and flag to overwrite
    - Choosing base VCS path to allow running for a different directory
    - Filtering `vendor/` directories (if this is the best place to do it, or leave it to go/type ast packages)
    - Check subdirectories if ran from a subdirectory of the VCS (currently checks all committed code)
- Add docs, flow diagram and fixing of existing docs
- Improve output formats (such as vim quickfix)
- Move these tasks to GitHub issues
- Once all other steps have been completed, performance will be investigated

# Testing

This uses golden masters for the tests, currently (and only due to time constraints) `testdata/` directory contains `before.go`
and `after.go`, which are before and after versions of a test package, each time `go test` is ran, the output is compared to
`testdata/exp.txt`, which should not change.

If adding new test cases, you should expect the test to fail as the code changes should create a difference with `exp.txt`.
Then, you'll need to update the golden master (see below), and commit those changes. If you add a new test case to `before.go` and
`after.go`, and the tests still pass, you've uncovered a bug within `apicompat` which will need a code change to fix, once
code has change, the tests should fail, so update the master, review all your changes and commit.

- This uses golden master `testdata/exp.txt` for the tests
- Run tests with: `go test`
- Update master with: `go test -args update`
- Alternatively to do a test run: `go install && ( cd testgit; ./make.sh && apicompat )`


apicompat

Converts golang AST to JSON and JSON to AST.

# asty

![GitHub go.mod Go version](https://img.shields.io/github/go-mod/go-version/asty-org/asty)
[![Go Reference](https://pkg.go.dev/badge/github.com/asty-org/asty.svg)](https://pkg.go.dev/github.com/asty-org/asty)
[![Go Report Card](https://goreportcard.com/badge/github.com/asty-org/asty)](https://goreportcard.com/report/github.com/asty-org/asty)
![Codecov](https://img.shields.io/codecov/c/github/asty-org/asty)
[![GitHub last commit](https://img.shields.io/github/last-commit/asty-org/asty)](https://github.com/asty-org/asty)
[![Docker Pulls](https://img.shields.io/docker/pulls/astyorg/asty)](https://hub.docker.com/r/astyorg/asty)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go#code-analysis)

_Not another JSON parser!_

**AST &#8594; JSON** | **JSON &#8594; AST**

Marshals golang [AST](https://pkg.go.dev/go/ast) into JSON and unmarshals it back from JSON.

It allows building pattern matching, statistical analysis, language transformation, search/data-mine/anything algorithms
for golang with any other language (I like to do it with python. Check out [asty-python](https://github.com/asty-org/asty-python))

## Example

[Try it!](https://asty-org.github.io/)

Input golang source

```golang
package main

import "fmt"

func main() {
 fmt.Println("hello world")
}
```

Ouput AST in JSON

```json
{
 "NodeType": "File",
 "Name": {
 "NodeType": "Ident",
 "Name": "main"
 },
 "Decls": [
 {
 "NodeType": "GenDecl",
 "Tok": "import",
 "Specs": [
 {
 "NodeType": "ImportSpec",
 "Name": null,
 "Path": {
 "NodeType": "BasicLit",
 "Kind": "STRING",
 "Value": "\"fmt\""
 }
 }
 ]
 },
 {
 "NodeType": "FuncDecl",
 "Recv": null,
 "Name": {
 "NodeType": "Ident",
 "Name": "main"
 },
 "Type": {
 "NodeType": "FuncType",
 "TypeParams": null,
 "Params": {
 "NodeType": "FieldList",
 "List": null
 },
 "Results": null
 },
 "Body": {
 "NodeType": "BlockStmt",
 "List": [
 {
 "NodeType": "ExprStmt",
 "X": {
 "NodeType": "CallExpr",
 "Fun": {
 "NodeType": "SelectorExpr",
 "X": {
 "NodeType": "Ident",
 "Name": "fmt"
 },
 "Sel": {
 "NodeType": "Ident",
 "Name": "Println"
 }
 },
 "Args": [
 {
 "NodeType": "BasicLit",
 "Kind": "STRING",
 "Value": "\"hello world\""
 }
 ]
 }
 }
 ]
 }
 }
 ]
}
```

## Install

Install `asty` under `$GOPATH/bin`

```bash
go install github.com/asty-org/asty

asty -h
```

## Building

Just `make`
If you want to do it differently use `go build`

## Usage

Convert AST to JSON

```bash
asty go2json -input <input.go> -output <output.json>
```

Convert JSON to AST

```bash
asty json2go -input <input.json> -output <output.go>
```

Use `asty help` for more information

Using with docker

```bash
docker run astyorg/asty go2json -input <input.go> -output <output.json>
```

## Development principles

- Make json output as close to real golang structures as possible. There is no additional logic introduced.
 No normalization. No reinterpretation. The only things that were introduced are the names of some enum values.
- Make it very explicit. No reflection. No listing of fields. This is done to facilitate future maintenance.
 If something will be changed in future versions of golang this code will probably break compile-time.
- Keep polymorphism in JSON structure. If some field references _expression_ then particular type will be
 discriminated from object type name stored in separate field.

## Other solutions

- https://github.com/ReconfigureIO/goblin reinterpret some structures (trying to simplify).
 Out of maintenance for a long time. Still works in some forks.
- https://github.com/CreativeInquiry/go2json tries to parse golang code with parser written in javascript.
 Also lacks maintenance. Developed for particular use case of HaXe traspiler.

## Article

I wrote [an article](https://dev.to/evgenus/analyzing-ast-in-go-with-json-tools-36dg) about this project.

asty

blanket is a tool that helps you catch functions which don't have direct unit tests in your Go packages.

# blanket

`blanket` is a tool that helps you catch functions which don't have direct unit tests in your Go packages.

## Installation

 go get -u gitlab.com/verygoodsoftwarenotvirus/blanket

## Docker Image

If you don't want to install blanket locally, you can use the pre-built Docker image like so:

 docker run -it --rm -v "$(pwd):/src/<pkg>" verygoodsoftwarenotvirus/blanket:latest analyze --package <pkg>

Where `<pkg>` could be something like `gitlab.com/verygoodsoftwarenotvirus/blanket/analysis`. :)

## Purpose

Say, for example, you had the following Go file:

```go
package simple

func A() string {
 return "A"
}

func B() string {
 return "B"
}

func C() string {
 return "C"
}

func wrapper() {
 A()
 B()
 C()
}
```

and you had the following test for that file:

```go
package simple

import (
 "testing"
)

func TestA(t *testing.T) {
 A()
}

func TestC(t *testing.T) {
 C()
}

func TestWrapper(t *testing.T) {
 wrapper()
}
```

Running `go test -cover` on that package yields the following output:

```bash
PASS
coverage: 100.0% of statements
ok gitlab.com/verygoodsoftwarenotvirus/blanket/example_packages/simple 0.006s
```

However, note that `B` doesn't have a direct test the way that `A` and `C` do. `B` is only "tested" in `TestWrapper`. Because all the functions are called, `-cover` yields a 100% coverage value. If you ever decide that `wrapper` doesn't need to call `B` anymore, and don't delete the function entirely, you'll have a drop in coverage. Running `blanket analyze` on that same package yields the following output:

```bash
Functions without direct unit tests:
in /Users/vgsnv/golang/src/gitlab.com/verygoodsoftwarenotvirus/blanket/example_packages/simple/main.go:
 B on line 7

Grade: 75% (3/4 functions)
```

Additionally, you can use the `cover` command to visualize those functions by passing in a cover profile. So if you run something like `go test -coverprofile=coverage.out && blanket cover --html=coverage.out`, a browser window will open that shows untested functions in red, functions without direct tests in yellow, and functions that are directly tested in green, like so:

![example output](example_files/cover_screenshot.png)

## Use Cases

What `blanket` seeks to do is catch these sorts of things so that package maintainers can decide what the appropriate course of action is. If you're fine with it, that's cool. If you're not cool with it, then you know what needs to have tests added.

You can also use `blanket` in your CI pipeline to decline PRs that would add functions that don't have direct unit tests. As a matter of fact, `blanket` does just that for itself! [Here](https://gitlab.com/verygoodsoftwarenotvirus/blanket/merge_requests/22) is an example of such a scenario working on this very repository!

I think `blanket` could also be helpful for new developers looking to contribute towards a project. They can run `blanket` on the package and see if there are some functions they could easily add unit tests for, just to get their feet wet in a project.

## Issues

If you've tried blanket on something and found that it didn't accurately handle some code, or panicked, please feel free to [file an issue](https://gitlab.com/verygoodsoftwarenotvirus/blanket/issues/new). Having an example of the code you experienced issues with is pretty crucial, so keep that in mind.

## Known Issues

`blanket` doesn't adequately handle deeply nested method calls. So if you had something like this:

```go
package main

import (
 "testing"
)

/*
// in another file:
type Example struct{}
func methodCall() {
 return
}
*/

func TestMethod(t *testing.T) {
 x := struct{
 First: struct{
 Second: struct{
 Third: Example{},
 },
 },
 }
 x.First.Second.Third.methodCall()
}
```

That should technically satisfy blanket's strict testing requirement, but it doesn't. Blanket can handle single-level selector expressions with great ease, but it doesn't recursively dive into those selectors for a number of reasons.

blanket

Find which of your Go lang direct GitHub dependencies is susceptible to ChainJacking attack.

![readme cover image](https://user-images.githubusercontent.com/1287098/142020269-af916c4d-7c66-4893-a030-daa4113e00f4.png)

ChainJacking is a tool to find which of your Go lang direct GitHub dependencies is susceptible to RepoJacking attack. Read more about it [here](https://checkmarx.com/blog/a-new-type-of-supply-chain-attack-could-put-popular-admin-tools-at-risk/)

[![repojacking explained](https://img.youtube.com/vi/xrafnrkKfEg/0.jpg)](https://www.youtube.com/watch?v=xrafnrkKfEg)


#### Requirements
- Python 3.6+ and pip
- Go and it's binaries >= 1.13
- GitHub token (for API queries) 
 - 💡 This token is used for read only purposes and does not require any permissions 

#### Installation
```
pip install chainjacking
```

## Using in CI Workflows
ChainJacking can be easily integrated into modern CI workflows to test new code contributions. 


### GitHub Actions

https://user-images.githubusercontent.com/1287098/142009618-5eb5d87c-a001-4536-abf3-c5d06216e1b6.mp4

Example configuration:
```yaml
name: Pull Request

on:
 pull_request

jobs:

 build:
 name: Run Tests
 runs-on: ubuntu-latest
 steps:
 - name: Checkout code
 uses: actions/checkout@v2
 - uses: actions/setup-python@v2
 with:
 python-version: '3.9'

 - name: ChainJacking tool test
 env:
 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 run: |
 python -m pip install -q chainjacking
 python -m chainjacking -gt $GITHUB_TOKEN
```


## CLI
ChainJacking module can be run as a CLI tool simply as 
```
python -m chainjacking
```

### CLI Arguments
- `-gt <token>` - GitHub access token, to run queries on GitHub API (required)
- `-p <path>` - Path to scan. (default=current directory)
- `-v` - Verbose output mode
- `-url <url>` - Scan one or more GitHub URLs
- `-f <path>` - Scan one or more GitHub URLs from a file separated by new-line


#### Example: Scan a Go project
navigate your shell into a Go project's directory, and run:
```
python -m chainjacking -gt $GH_TOKEN
```

https://user-images.githubusercontent.com/1287098/142020377-c873716d-c080-418b-8597-f9e08dba3e82.mp4

ChainJacking

# Chronos


 <img src="https://i.imgur.com/AhLyxVh.jpeg" width="150" height="225">


[![made-with-Go](https://github.com/go-critic/go-critic/workflows/Go/badge.svg)](http://golang.org)
[![made-with-Go](https://img.shields.io/badge/Made%20with-Go-1f425f.svg)](http://golang.org)
[![MIT license](https://img.shields.io/badge/License-MIT-blue.svg)](https://lbesson.mit-license.org/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
[![amit-davidson](https://circleci.com/gh/amit-davidson/Chronos.svg?style=svg)](https://app.circleci.com/pipelines/github/amit-davidson/Chronos)

Chronos is a static race detector for the Go language written in Go.

## Quick Start:

Download the package

```
go get -v github.com/amit-davidson/Chronos/cmd/chronos
```

Pass the entry point

```
chronos --file <path_to_main> --mod <path_to_module>
```

Help

```
Usage of ./chronos:
 --file string
 	The file containing the entry point of the program
 --mod string
 	Absolute or relative path to the module where the search should be performed. Should end in the format:{VCS}/{organization}/{package}. Packages outside this path are excluded rom the search.
```

## Example:


 <img src="https://i.imgur.com/LJMP9c2.png" width="245" height="300">
 <img src="https://i.imgur.com/X89VVfr.png" width="700" height="300">


## Features:

Support:

- Detects races on pointers passed around the program.
- Analysis of conditional branches, nested functions, interfaces, select, gotos, defers, for loops and recursions.
- Synchronization using mutex and goroutines starts.

Limitations:

- Big programs and external packages. (Due to stack overflow)
- Synchronization using channels, waitgroups, once, cond and atomic.

## Chronos vs go race:

Chronos successfully reports cases where go race fails thanks to it's static nature. Mostly because data races appear in unexpected production workloads, which are hard to produce in dev.
In addition, go race is having trouble with short programs where without contrived synchronization the program may exit too quickly.

In contrast, Chronos managed to report only 244/403 = 60.5% of go race test cases. This can be explained by Chronos partial support with Go's features so this number will increase in the future.
Also, it lacked due to his static nature where context/path sensitivity was required.

Therefore, I suggest using both according the strengths and weaknesses of each of the race detectors.

## Credits:

Jan Wen, J., Jhala, R., &amp; Lerner, S. (n.d.). [RELAY: Static Race Detection on Millions of Lines of Code](https://cseweb.ucsd.edu/~lerner/papers/relay.pdf) 
Colin J. Fidge (February 1988). [Timestamps in Message-Passing Systems That Preserve the Partial Ordering"](http://zoo.cs.yale.edu/classes/cs426/2012/lab/bib/fidge88timestamps.pdf)

## More examples:


 <img src="https://i.imgur.com/NvVWFRf.png" width="230" height="440">
 <img src="https://i.imgur.com/eCNFAX7.png" width=600" height="300">

<hr style="border:2px solid gray"> </hr>

Chronos

# dupl [![Build Status](https://travis-ci.org/mibk/dupl.png)](https://travis-ci.org/mibk/dupl)

**dupl** is a tool written in Go for finding code clones. So far it can find clones only
in the Go source files. The method uses suffix tree for serialized ASTs. It ignores values
of AST nodes. It just operates with their types (e.g. `if a == 13 {}` and `if x == 100 {}` are
considered the same provided it exceeds the minimal token sequence size).

Due to the used method dupl can report so called "false positives" on the output. These are
the ones we do not consider clones (whether they are too small, or the values of the matched
tokens are completely different).

## Installation

```bash
go get -u github.com/mibk/dupl
```

## Usage

```
Usage of dupl:
  dupl [flags] [paths]

Paths:
  If the given path is a file, dupl will use it regardless of
  the file extension. If it is a directory it will recursively
  search for *.go files in that directory.

  If no path is given dupl will recursively search for *.go
  files in the current directory.

Flags:
  -files
        read file names from stdin one at each line
  -html
        output the results as HTML, including duplicate code fragments
  -plumbing
        plumbing (easy-to-parse) output for consumption by scripts or tools
  -t, -threshold size
        minimum token sequence size as a clone (default 15)
  -vendor
        check files in vendor directory
  -v, -verbose
        explain what is being done

Examples:
  dupl -t 100
        Search clones in the current directory of size at least
        100 tokens.
  dupl $(find app/ -name '*_test.go')
        Search for clones in tests in the app directory.
  find app/ -name '*_test.go' |dupl -files
        The same as above.
```

## Example

The reduced output of this command with the following parameters for the [Docker](https://www.docker.com) source code
looks like [this](http://htmlpreview.github.io/?https://github.com/mibk/dupl/blob/master/_output_example/docker.html).

```bash
$ dupl -t 200 -html >docker.html
```


dupl

Errcheck is a program for checking for unchecked errors in Go programs.

errcheck

go-cleanarch was created to validate Clean Architecture rules, like a The Dependency Rule and interaction between packages in your Go projects.

# Clean Architecture checker for Golang

[![Go Report Card](https://goreportcard.com/badge/github.com/roblaszczak/go-cleanarch)](https://goreportcard.com/report/github.com/roblaszczak/go-cleanarch)

go-cleanarch was created to keep Clean Architecture rules,
like a _The Dependency Rule_ and _interaction between modules_ in your Go projects.
For more information you should read [our article about Clean Architecture](https://threedots.tech/post/introducing-clean-architecture/?utm_source=go-cleanarch).


Some benefits of using Clean Architecture:

> 1. Independent of Frameworks. The architecture does not depend on the existence of some library of feature laden software. This allows you to use such frameworks as tools, rather than having to cram your system into their limited constraints.
> 2. Testable. The business rules can be tested without the UI, Database, Web Server, or any other external element.
> 3. Independent of UI. The UI can change easily, without changing the rest of the system. A Web UI could be replaced with a console UI, for example, without changing the business rules.
> 4. Independent of Database. You can swap out Oracle or SQL Server, for Mongo, BigTable, CouchDB, or something else. Your business rules are not bound to the database.
> 5. Independent of any external agency. In fact your business rules simply don’t know anything at all about the outside world.

_Source: The Clean Architecture_

![Clean Architecture](docs/go-cleanarch.png)

### Project schema requirements

go-cleanarch assumes this files structure:

 [GOPATH]/[PACKAGE_NAME]/[LAYER_NAME]

or

 [GOPATH]/[PACKAGE_NAME]/[MODULE_NAME]/[LAYER_NAME]

For example

* go/src/github.com/roblaszczak/awesome-app
 * auth
 * domain
 * application
 * interfaces
 * content
 * domain
 * submodule1
 * submodule2
 * *etc.*
 * application
 * interfaces
 * frontend
 * domain
 * application
 * interfaces

### Allowed `LAYER_NAME`:

The default layer names are as followed. It is possible to set different names
by command line parameters see -domain/-application/-interfaces/-infrastructure
bellow.

 var LayersAliases = map[string]Layer{
 // Domain
 "domain": LayerDomain,
 "entities": LayerDomain,

 // Application
 "app": LayerApplication,
 "application": LayerApplication,
 "usecases": LayerApplication,
 "usecase": LayerApplication,
 "use_cases": LayerApplication,

 // Interfaces
 "interfaces": LayerInterfaces,
 "interface": LayerInterfaces,
 "adapters": LayerInterfaces,
 "adapter": LayerInterfaces,

 // Infrastructure
 "infrastructure": LayerInfrastructure,
 "infra": LayerInfrastructure,
 }

For examples please go to [examples](examples/) directory,
with contains examples of valid and invalid architectures.

For more information you should read [our article about Clean Architecture](https://threedots.tech/post/introducing-clean-architecture/?utm_source=go-cleanarch).

## Installing

 go install github.com/roblaszczak/go-cleanarch@latest

_go-cleanarch was only tested on Linux and also should work on OS X.
Probably it doesn't work well on Windows._

## Running

To run in the current directory:

 go-cleanarch

To run in provided directory

 go-cleanarch go/src/github.com/roblaszczak/awesome-cms

Process will exit with code `1` if architecture is not valid, otherwise it will exit with `0`.

### -ignore-tests

If you need to ignore `*_test.go` files in `go-cleanarch` check you can pass `-ignore-tests`

 go-cleanarch -ignore-tests

It is useful when you have memory implementation in infrastructure layer
and you need to test application service which depends of it.

### -ignore-package

If for some reason you need to allow to make forbidden import, for example

`github.com/roblaszczak/go-cleanarch/examples/ignore-package/app` to `github.com/roblaszczak/go-cleanarch/examples/ignore-package/domain`.

you can use

 go-cleanarch -ignore-package=github.com/roblaszczak/go-cleanarch/examples/ignore-package/app 

### Layer names

The layer names can be set to a specific value with the following parameters. Each
parameter stands for on layer.

 go-cleanarch -domain dom -application appli -interfaces int -infrastructure outer

This would only allow the domain name to be dom, application hast to be appli,
interafces must be int and infrastructure must be outer.

## Running the tests

 make test

## And coding style tests

 make qa

## Contributing

Please read [CONTRIBUTING.md](https://gist.github.com/PurpleBooth/b24679402957c63ec426) for details on our code of conduct, and the process for submitting pull requests to us.

## Versioning

We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/your/project/tags).

## Credits

Made without love by Robert Laszczak </3

## License

This project is licensed under the MIT License.

go-cleanarch

source code linter that brings checks that are currently not implemented in other linters.

go-critic

Console application that displays outdated packages.

# This project is not supported anymore

Go-outdated is minimalistic library that helps to find outdated packages hosted on github.com in your golang project.

![Dashboard](https://raw.githubusercontent.com/firstrow/go-outdated/master/sample.png)

## Installation
Install the library with:
``` bash
go get -u github.com/firstrow/go-outdated
```

## Usage
Note: To use this library without limitations, you should create GitHub access token.
``` bash
cd $GOPATH/path/to/your/project
go-outdated
```

## GitHub access token
GitHub API has requests limit. You should create access token and pass it to `go-outdated`
``` bash
go-outdated -token=YOUR_PRIVATE_GITHUB_TOKEN
```

## Re-entering API token
Yes, typing each time access token in command-line is not easy. Use git config to re-use token:
``` bash
git config --global github.token YOUR_PRIVATE_GITHUB_TOKEN
go-outdated # token will be taken from git config
```
Github doc: https://github.com/blog/180-local-github-config

## Aliases
If you for some reason do not want to configure you local git config, You can create command-line alias in your `.zshrc` or `.bashrc` files. Example:
``` bash
alias go-outdated='go-outdated -token=YOUR_PRIVATE_GITHUB_TOKEN'
```

## Todo
- Cache
- Refactor

## Links
How-to create API tokens: https://help.github.com/articles/creating-an-access-token-for-command-line-use/  

## Alternatives:
https://github.com/shurcooL/Go-Package-Store  
https://github.com/divan/gofresh

## License:
The MIT License (MIT) 
http://opensource.org/licenses/MIT


go-outdated

GoAst Viewer
================================================================

Golang AST visualizer.

## Demo

[GoAst Viewer Demo](https://yuroyoro.github.io/goast-viewer/index.html)

![](https://raw.githubusercontent.com/yuroyoro/goast-viewer/master/goast-viewer.png)


## Usage

You just need to run a http server and open your browser to `index.html`


## Installation

To install, use `go get` and `make install`.

```bash
$ go get -d github.com/yuroyoro/goast-viewer
$ cd $GOPATH/src/github.com/yuroyoro/goast-viewer
$ make build
```

## Authors

- [yuroyoro](https://github.com/yuroyoro)
- [paulvollmer](https://github.com/paulvollmer)


goast-viewer

# golang-ifood-sdk
A golang Ifood sdk 

![Actions on main](https://github.com/arxdsilva/golang-ifood-sdk/actions/workflows/test.yml/badge.svg?branch=main)
[![Coverage Status](https://coveralls.io/repos/github/arxdsilva/golang-ifood-sdk/badge.svg?branch=main)](https://coveralls.io/github/arxdsilva/golang-ifood-sdk?branch=main)
[![Go Report Card](https://goreportcard.com/badge/github.com/arxdsilva/golang-ifood-sdk)](https://goreportcard.com/report/github.com/arxdsilva/golang-ifood-sdk)
[![LICENSE](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)
[![GoDoc](https://godoc.org/github.com/arxdsilva/golang-ifood-sdk?status.svg)](https://godoc.org/github.com/arxdsilva/golang-ifood-sdk)

## Usage V2

```go

package main

import (
    sdk "github.com/arxdsilva/golang-ifood-sdk/container"
)

func main() {
    var clientID, clientSecret, user, password string
    clientID = os.GetEnv("CLIENT_ID")
    clientSecret = os.GetEnv("CLIENT_SECRET")
    // START new SDK instance
    container := sdk.Create(clientID, clientSecret, 0, true)
    // Get user code to connect this supplier to the restaurant
    uc, err := container.AuthService.V2GetUserCode()
    if err != nil { 
        log.Fatal(err)
    }
    fmt.Println("user_code_url_complete:", uc.VerificationURLComplete)
    v2Creds, err := container.AuthService.V2Authenticate("client_credentials", uc.Usercode, uc.AuthorizationCodeVerifier)
    if err != nil { 
        log.Fatal(err)
    }
    events, err := container.EventsService.V2Poll()
    if err != nil {
        log.Fatal(err)
    }
    err = container.EventsService.V2Acknowledge(events)
    if err != nil {
        log.Fatal(err)
    }
    var newOrdersDetails []orders.OrderDetails
	for _, event := range events {
        // avoid non new orders
        if event.Code != "PLACED" {
            continue
        }
        details, err := container.OrdersService.V2GetDetails(event.ID)
        if err != nil {
            fmt.Println("err: ", err)
            continue
        }
        newOrdersDetails = append(newOrdersDetails, details)
	}
	for _, order := range newOrdersDetails {
        // change order status
        err = container.OrdersService.V2SetConfirmStatus(order.ID)
        if err != nil {
            fmt.Println("err: ", err)
            continue
        }
        // change other statuses
    }
    fmt.Printf("new orders: %+v\n", newOrdersDetails)
}
```


## Usage V1

```go

package main

import (
    sdk "github.com/arxdsilva/golang-ifood-sdk/container"
)

func main() {
    var clientID, clientSecret, user, password string
    clientID = os.GetEnv("CLIENT_ID")
    clientSecret = os.GetEnv("CLIENT_SECRET")
    // START new SDK instance
    container := sdk.New(0, time.Minute, false)
    container.GetHttpAdapter()
    // Alocate services
    container.GetAuthenticationService(clientID, clientSecret)
    container.GetMerchantService()
    container.GetCatalogService()
    container.GetEventsService()
    container.GetOrdersService()
    user = os.GetEnv("USER")
    password = os.GetEnv("PASSWORD")
    creds, err := container.AuthService.Authenticate(user,password)
    if err != nil { 
        log.Fatal(err)
    }
    merchants, err := container.MerchantService.ListAll()
    if err != nil { 
        log.Fatal(err)
    }
    events, err := container.EventsService.Poll()
    if err != nil {
        log.Fatal(err)
    }
    var newOrdersDetails []orders.OrderDetails
    for _, event := range events {
        err = container.EventsService.Acknowledge(event)
        if err != nil {
            fmt.Println("err: ", err)
            continue
        }
        // avoid non new orders
        if event.Code != "PLACED" {
            continue
        }
        details, err := container.OrdersService.GetDetails(event.ID)
        if err != nil {
            fmt.Println("err: ", err)
            continue
        }
        newOrdersDetails = append(newOrdersDetails, details)
	}
	for _, order := range newOrdersDetails {
        // change order status
        err = container.OrdersService.SetIntegrateStatus(order.ID)
        if err != nil {
            fmt.Println("err: ", err)
            continue
        }
        // change other statuses
    }
    fmt.Printf("new orders: %+v\n", newOrdersDetails)
}
```


golang-ifood-sdk

Formatter that automatically shortens long lines in Go code.

[![golines test](https://github.com/segmentio/golines/actions/workflows/test.yml/badge.svg)](https://github.com/segmentio/golines/actions/workflows/test.yml)
[![Go Report Card](https://goreportcard.com/badge/github.com/segmentio/golines)](https://goreportcard.com/report/github.com/segmentio/golines)
[![GoDoc](https://godoc.org/github.com/segmentio/golines?status.svg)](https://godoc.org/github.com/segmentio/golines)

# golines

Golines is a Go code formatter that shortens long lines, in addition to all
of the formatting fixes done by [`gofmt`](https://golang.org/cmd/gofmt/).

## Motivation

The standard Go formatting tools (`gofmt`, `goimports`, etc.) are great, but
[deliberately don't shorten long lines](https://github.com/golang/go/issues/11915);
instead, this is an activity left to developers.

While there are different tastes when it comes to line lengths in go, we've generally found
that very long lines are more difficult to read than their shortened alternatives. As an example:

```go
myMap := map[string]string{"first key": "first value", "second key": "second value", "third key": "third value", "fourth key": "fourth value", "fifth key": "fifth value"}
```

vs.

```go
myMap := map[string]string{
	"first key": "first value",
	"second key": "second value",
	"third key": "third value",
	"fourth key": "fourth value",
	"fifth key": "fifth value",
}
```

We built `golines` to give Go developers the option to automatically shorten long lines, like
the one above, according to their preferences.

More background and technical details are available in
[this blog post](https://yolken.net/blog/cleaner-go-code-golines).

## Examples

See this [before](_fixtures/end_to_end.go) and [after](_fixtures/end_to_end__exp.go)
view of a file with very long lines. More example pairs can be found in the
[`_fixtures`](_fixtures) directory.

## Version support

Newer releases of `golines` require at least Go 1.18 due to generics-related dependencies.
However, the [minimum version](https://go.dev/ref/mod#go-mod-file-go) in [`go.mod`](./go.mod)
should be considered the minimum required version of Go for any given version
of `golines.` If you need to use `golines` with an older version of go, install
the tool from the `v0.9.0` release.

## Usage

First, install the tool. If you're using Go 1.21 or newer, run:

```text
go install github.com/segmentio/golines@latest
```

Otherwise, for older Go versions, run:

```text
go install github.com/segmentio/golines@v0.9.0
```

Then, run:

```text
golines [paths to format]
```

The paths can be either directories or individual files. If no paths are
provided, then input is taken from `stdin` (as with `gofmt`).

By default, the results are printed to `stdout`. To overwrite the existing
files in place, use the `-w` flag.

## Options

Some other options are described in the sections below. Run `golines --help` to
see all available flags and settings.

### Line length settings

By default, the tool tries to shorten lines that are longer than 100 columns
and assumes that 1 tab = 4 columns. The latter can be changed via the
`-m` and `-t` flags respectively.

#### Dry-run mode

Running the tool with the `--dry-run` flag will show pretty, git-style diffs.

#### Comment shortening

Shortening long comment lines is harder than shortening code because comments can
have arbitrary structure and format. `golines` includes some basic
logic for shortening single-line (i.e., `//`-prefixed) comments, but this is turned
off by default since the quality isn't great. To enable this feature anyway, run
with the `--shorten-comments` flag.

#### Custom formatters

By default, the tool will use [`goimports`](https://godoc.org/golang.org/x/tools/cmd/goimports)
as the base formatter (if found), otherwise it will revert to `gofmt`. An explicit
formatter can be set via the `--base-formatter` flag; the command provided here
should accept its input via `stdin` and write its output to `stdout`.

#### Generated files

By default, the tool will not format any files that look like they're generated.
If you want to reformat these too, run with the flag `--ignore-generated=false`.

#### Chained method splitting

There are several possible ways to split lines that are part of
[method chains](https://en.wikipedia.org/wiki/Method_chaining). The original
approach taken by `golines` was to split on the args, e.g.:

```go
myObj.Method(
	arg1,
	arg2,
	arg3,
).AnotherMethod(
	arg1,
	arg2,
).AThirdMethod(
	arg1,
	arg2,
)
```

Starting in version 0.3.0, the tool now splits on the dots by default, e.g.:

```go
myObj.Method(arg1, arg2, arg3).
	AnotherMethod(arg1, arg2).
	AThirdMethod(arg1, arg2)
```

The original behavior can be used by running the tool with the
`--no-chain-split-dots` flag.

#### Struct tag reformatting

In addition to shortening long lines, the tool also aligns struct tag keys; see the
associated [before](_fixtures/struct_tags.go) and [after](_fixtures/struct_tags__exp.go)
examples in the `_fixtures` directory. To turn this behavior off, run with `--no-reformat-tags`.

## Developer Tooling Integration

### vim-go

Add the following lines to your vimrc, substituting `128` with your preferred line length:

```vim
let g:go_fmt_command = "golines"
let g:go_fmt_options = {
    \ 'golines': '-m 128',
    \ }
```

### Visual Studio Code

1. Install the [Run on Save](https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave) extension
2. Go into the VSCode settings menu, scroll down to the section for the "Run on Save"
  extension, click the "Edit in settings.json" link
3. Set the `emeraldwalk.runonsave` key as follows
   (adding other flags to the `golines` command as desired):
```
    "emeraldwalk.runonsave": {
        "commands": [
            {
                "match": "\\.go$",
                "cmd": "golines ${file} -w"
            }
        ]
    }
```

1. Save the settings and restart VSCode

### Goland

1. Go into the Goland settings and click "Tools" -> "File Watchers" then click the plus to create a new file watcher
2. Set the following properties and confirm by clicking OK:
   - __Name:__ `golines`
   - __File type:__ `Go files`
   - __Scope:__ `Project Files`
   - __Program:__ `golines`
   - __Arguments:__ `$FilePath$ -w`
   - __Output paths to refresh:__ `$FilePath$`
3. Activate your newly created file watcher in the Goland settings under "Tools" -> "Actions on save"

### Others

Coming soon.

## How It Works

For each input source file, `golines` runs through the following process:

1. Read the file, break it into lines
2. Add a specially-formatted annotation (comment) to each line that's longer
  than the configured maximum
3. Use [Dave Brophy's](https://github.com/dave) excellent
  [decorated syntax tree](https://github.com/dave/dst) library to parse the code
  plus added annotations
4. Do a depth-first traversal of the resulting tree, looking for nodes
  that have an annotation on them
5. If a node is part of a line that's too long, shorten it by altering
  the newlines around the node and/or its children
6. Repeat steps 2-5 until no more shortening can be done
7. Run the base formatter (e.g., `gofmt`) over the results, write these to either
  `stdout` or the source file

See [this blog post](https://yolken.net/blog/cleaner-go-code-golines) for more technical details.

## Limitations

The tool has been tested on a variety of inputs, but it's not perfect. Among
other examples, the handling of long lines in comments could be improved. If you see
anything particularly egregious, please report via an issue.


golines

Library and CLI that generates text plantump class diagram containing information about structures and interfaces with the relationship among them.

[![godoc reference](https://img.shields.io/badge/godoc-reference-blue.svg)](https://godoc.org/github.com/jfeliu007/goplantuml/parser) [![Go Report Card](https://goreportcard.com/badge/github.com/jfeliu007/goplantuml)](https://goreportcard.com/report/github.com/jfeliu007/goplantuml) [![codecov](https://codecov.io/gh/jfeliu007/goplantuml/branch/master/graph/badge.svg)](https://codecov.io/gh/jfeliu007/goplantuml) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![GitHub release](https://img.shields.io/github/release/jfeliu007/goplantuml.svg)](https://github.com/jfeliu007/goplantuml/releases/)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go) 
[![DUMELS Diagram](https://www.dumels.com/api/v1/badge/23ff0222-e93b-4e9f-a4ef-4d5d9b7a5c7d)](https://www.dumels.com/diagram/23ff0222-e93b-4e9f-a4ef-4d5d9b7a5c7d) 
# GoPlantUML V2

GoPlantUML is an open-source tool developed to streamline the process of generating PlantUML diagrams from Go source code. With GoPlantUML, developers can effortlessly visualize the structure and relationships within their Go projects, aiding in code comprehension and documentation. By parsing Go source code and producing PlantUML diagrams, GoPlantUML empowers developers to create clear and concise visual representations of their codebase architecture, package dependencies, and function interactions. This tool simplifies the documentation process and enhances collaboration among team members by providing a visual overview of complex Go projects. GoPlantUML is actively maintained and welcomes contributions from the Go community.

## Want to try it on your code? 
Take a look at [www.dumels.com](https://www.dumels.com). We have created dumels using this library. 

## Code of Conduct
Please, review the code of conduct [here](https://github.com/jfeliu007/goplantuml/blob/master/CODE_OF_CONDUCT.md "here").

### Prerequisites
golang 1.17 or above

### Installing

```
go get github.com/jfeliu007/goplantuml/parser
go install github.com/jfeliu007/goplantuml/cmd/goplantuml@latest
```

This will install the command goplantuml in your GOPATH bin folder.

### Usage

```
goplantuml [-recursive] path/to/gofiles path/to/gofiles2
```
```
goplantuml [-recursive] path/to/gofiles path/to/gofiles2 > diagram_file_name.puml
```
```
Usage of goplantuml:
 -aggregate-private-members
 Show aggregations for private members. Ignored if -show-aggregations is not used.
 -hide-connections
 hides all connections in the diagram
 -hide-fields
 hides fields
 -hide-methods
 hides methods
 -ignore string
 comma separated list of folders to ignore
 -notes string
 Comma separated list of notes to be added to the diagram
 -output string
 output file path. If omitted, then this will default to standard output
 -recursive
 walk all directories recursively
 -show-aggregations
 renders public aggregations even when -hide-connections is used (do not render by default)
 -show-aliases
 Shows aliases even when -hide-connections is used
 -show-compositions
 Shows compositions even when -hide-connections is used
 -show-connection-labels
 Shows labels in the connections to identify the connections types (e.g. extends, implements, aggregates, alias of
 -show-implementations
 Shows implementations even when -hide-connections is used
 -show-options-as-note
 Show a note in the diagram with the none evident options ran with this CLI
 -title string
 Title of the generated diagram
 -hide-private-members
 Hides all private members (fields and methods)
```

#### Example
```
goplantuml $GOPATH/src/github.com/jfeliu007/goplantuml/parser
```
```
// echoes

@startuml
namespace parser {
 class Struct {
 + Functions []*Function
 + Fields []*Parameter
 + Type string
 + Composition []string
 + Extends []string

 }
 class LineStringBuilder {
 + WriteLineWithDepth(depth int, str string) 

 }
 class ClassParser {
 - structure map[string]map[string]*Struct
 - currentPackageName string
 - allInterfaces map[string]struct{}
 - allStructs map[string]struct{}

 - structImplementsInterface(st *Struct, inter *Struct) 
 - parsePackage(node ast.Node) 
 - parseFileDeclarations(node ast.Decl) 
 - addMethodToStruct(s *Struct, method *ast.Field) 
 - getFunction(f *ast.FuncType, name string) 
 - addFieldToStruct(s *Struct, field *ast.Field) 
 - addToComposition(s *Struct, fType string) 
 - addToExtends(s *Struct, fType string) 
 - getOrCreateStruct(name string) 
 - getStruct(structName string) 
 - getFieldType(exp ast.Expr, includePackageName bool) 

 + Render() 

 }
 class Parameter {
 + Name string
 + Type string

 }
 class Function {
 + Name string
 + Parameters []*Parameter
 + ReturnValues []string

 }
}
strings.Builder *-- parser.LineStringBuilder


@enduml
```
```
goplantuml $GOPATH/src/github.com/jfeliu007/goplantuml/parser > ClassDiagram.puml
// Generates a file ClassDiagram.puml with the previous specifications
```

There are two different relationships considered in goplantuml:
- Interface implementation
- Type Composition

The following example contains interface implementations and composition. Notice how the signature of the functions
```golang
package testingsupport

//MyInterface only has one method, notice the signature return value
type MyInterface interface {
	foo() bool
}

//MyStruct1 will implement the foo() bool function so it will have an "extends" association with MyInterface
type MyStruct1 struct {
}

func (s1 *MyStruct1) foo() bool {
	return true
}

//MyStruct2 will be directly composed of MyStruct1 so it will have a composition relationship with it
type MyStruct2 struct {
	MyStruct1
}

//MyStruct3 will have a foo() function but the return value is not a bool, so it will not have any relationship with MyInterface
type MyStruct3 struct {
 Foo MyStruct1
}

func (s3 *MyStruct3) foo() {

}
```
This will be generated from the previous code
```
@startuml
namespace testingsupport {
 interface MyInterface {
 - foo() bool

 }
 class MyStruct1 << (S,Aquamarine) >> {
 - foo() bool

 }
 class MyStruct2 << (S,Aquamarine) >> {
 }
 class MyStruct3 << (S,Aquamarine) >> {
 - foo() 

 + Foo MyStruct1

 }
}
testingsupport.MyStruct1 *-- testingsupport.MyStruct2

testingsupport.MyInterface <|-- testingsupport.MyStruct1

testingsupport.MyStruct3 o-- testingsupport.MyStruct1

@enduml
```

![alt text](https://raw.githubusercontent.com/jfeliu007/goplantuml/master/example/example.png)

### Diagram using www.dumels.com
[UML Diagram](https://www.dumels.com/diagram/23ff0222-e93b-4e9f-a4ef-4d5d9b7a5c7d)

### Diagram rendered in plantuml online server
[UML Diagram](https://www.plantuml.com/plantuml/uml/SoWkIImgAStDuSfBp4qjBaXCJbKeIIqkoSnBBoujACWlAb6evb80WioyajIYD92qRwKdd0sIX09TXRJyV0rDXQJy_1mki6Wjc4pEIImk1ceABYagJIunLB2nKT08rd4iB4tCJIpAp4lLLB2p8zaO8np6uDHWJAozN70HRGMt_7o4ms6EgUL23HyzXDUqT7KLS4WQSM5gGmIZJGrkdOOOEX5-oiUhpI4rBmKOim00)

For instructions on how to render these diagrams locally using plantuml please visit [https://plantuml.com](https://plantuml.com)

GoPlantUML

Adds zero-value return statements to match the func return types.

This tool adds zero-value return values to incomplete Go return
statements, to save you time when writing Go. It is inspired by
and based on goimports.

![short screencast](screencast.gif)

full 30-second screencast: http://youtu.be/hyEMO9vtKZ8

For example, the following incomplete return statement:

	func F() (*MyType, int, error) { return errors.New("foo") }

is made complete by adding nil and 0 returns (the zero values for
*MyType and int):

	func F() (*MyType, int, error) { return nil, 0, errors.New("foo") }

To install:

	go get -u github.com/sqs/goreturns

To run:

	goreturns file.go

To view a diff showing what it'd do on a sample file:

	goreturns -d $GOPATH/github.com/sqs/goreturns/_sample/a.go

Editor integration: replace gofmt or goimports in your post-save hook
with goreturns. By default goreturns calls goimports on files before
performing its own processing.

It acts the same as gofmt (same flags, etc) but in addition to code
formatting, also fixes returns.


goreturns

Command line tool, shows the status of repositories that contain Go packages.

gostatus

Static code analyser which links TODO comments in code with issues in your issue tracker.

todocheck

Remove unnecessary type conversions from Go source.

# About

The unconvert program analyzes Go packages to identify unnecessary
type conversions; i.e., expressions T(x) where x already has type T.

# Install

    go install github.com/mdempsky/unconvert@latest

# Usage

    $ unconvert -v bytes fmt
    GOROOT/src/bytes/reader.go:117:14: unnecessary conversion
                    abs = int64(r.i) + offset
                               ^
    GOROOT/src/fmt/print.go:411:21: unnecessary conversion
            p.fmt.integer(int64(v), 16, unsigned, udigits)
                               ^

# Flags

Using the -v flag, unconvert will also print the source line and a
caret to indicate the unnecessary conversion's position therein.

Using the -apply flag, unconvert will rewrite the Go source files
without the unnecessary type conversions.

Using the -all flag, unconvert will analyze the Go packages under all
possible GOOS/GOARCH combinations, and only identify conversions that
are unnecessary in all cases.

E.g., syscall.Timespec's Sec and Nsec fields are int64 under
linux/amd64 but int32 under linux/386.  An int64(ts.Sec) conversion
that appears in a linux/amd64-only file will be identified as
unnecessary, but it will be preserved if it occurs in a file that's
compiled for both linux/amd64 and linux/386.


unconvert

A linter that detect the possibility to use variables/constants from the Go standard library.

<img align="right" alt="usestdlibvars" src="./assets/uslv_logo.svg">

# usestdlibvars

A linter that detect the possibility to use variables/constants from the Go standard library.

## Install

### `go install`

```bash
go install github.com/sashamelentyev/usestdlibvars@latest
```

### `golangci-lint`

`usestdlibvars` is already integrated with
[golangci-lint](https://github.com/golangci/golangci-lint).

## Usage

### Binary

```console
$ usestdlibvars -h
usestdlibvars: A linter that detect the possibility to use variables/constants from the Go standard library.

Usage: usestdlibvars [-flag] [package]


Flags:
 -V print version and exit
 -all
 no effect (deprecated)
 -c int
 display offending line with this many lines of context (default -1)
 -constant-kind
 suggest the use of constant.Kind.String()
 -cpuprofile string
 write CPU profile to this file
 -crypto-hash
 suggest the use of crypto.Hash.String()
 -debug string
 debug flags, any subset of "fpstv"
 -fix
 apply all suggested fixes
 -flags
 print analyzer flags in JSON
 -http-method
 suggest the use of http.MethodXX (default true)
 -http-status-code
 suggest the use of http.StatusXX (default true)
 -json
 emit JSON output
 -memprofile string
 write memory profile to this file
 -os-dev-null
 suggest the use of os.DevNull
 -rpc-default-path
 suggest the use of rpc.DefaultXXPath
 -source
 no effect (deprecated)
 -sql-isolation-level
 suggest the use of sql.LevelXX.String()
 -tags string
 no effect (deprecated)
 -test
 indicates whether test files should be analyzed, too (default true)
 -time-layout
 suggest the use of time.Layout
 -time-month
 suggest the use of time.Month.String()
 -time-weekday
 suggest the use of time.Weekday.String()
 -tls-signature-scheme
 suggest the use of tls.SignatureScheme.String()
 -trace string
 write trace log to this file
 -v no effect (deprecated)
```

### `golangci-lint`

```console
golangci-lint run --disable-all --enable usestdlibvars
```

## Examples

```go
package response

import (
	"bytes"
	"encoding/json"
	"net/http"
)

// JSON marshals v to JSON, automatically escaping HTML,
// setting the Content-Type header as "application/json; charset=utf-8",
// sends an HTTP response header with the provided statusCode and
// writes the marshaled v as bytes to the connection as part of an HTTP reply.
func JSON(w http.ResponseWriter, statusCode int, v any) {
	var buf bytes.Buffer
	enc := json.NewEncoder(&buf)
	enc.SetEscapeHTML(true)
	if err := enc.Encode(v); err != nil {
		http.Error(w, err.Error(), 500)
		return
	}
	w.Header().Set("Content-Type", "application/json; charset=utf-8")
	w.WriteHeader(statusCode)
	if _, err := w.Write(buf.Bytes()); err != nil {
		http.Error(w, err.Error(), 500)
		return
	}
}
```

```bash
usestdlibvars ./...
```

```console
response.go:18:30: "500" can be replaced by http.StatusInternalServerError
response.go:24:30: "500" can be replaced by http.StatusInternalServerError
```

## Sponsors

[<img src="https://evrone.com/logo/evrone-sponsored-logo.png">](https://evrone.com/?utm_source=usestdlibvars)

usestdlibvars

An ultra-super-fast, lightweight OpenAPI linter and quality checking tool.

![logo](logo.png)

# vacuum - The world's fastest OpenAPI & Swagger linter.

![build](https://github.com/daveshanley/vacuum/workflows/Build/badge.svg)
[![Go Report Card](https://goreportcard.com/badge/github.com/daveshanley/vacuum)](https://goreportcard.com/report/github.com/daveshanley/vacuum)
[![discord](https://img.shields.io/discord/923258363540815912)](https://discord.gg/UAcUF78MQN)
[![Docs](https://img.shields.io/badge/godoc-reference-5fafd7)](https:/-/pkg.go.dev/github.com/daveshanley/vacuum)
[![GitHub downloads](https://img.shields.io/github/downloads/daveshanley/vacuum/total?label=github%20downloads&style=flat-square)](https://github.com/daveshanley/vacuum/releases)
[![npm](https://img.shields.io/npm/dm/@quobix/vacuum?style=flat-square&label=npm%20downloads)](https://www.npmjs.com/package/@quobix/vacuum)
[![Docker Pulls](https://img.shields.io/docker/pulls/dshanley/vacuum?style=flat-square)](https://hub.docker.com/r/dshanley/vacuum)
[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge-flat.svg)](https://github.com/avelino/awesome-go)

An **ultra-super-fast**, lightweight OpenAPI linter and quality checking tool, written in golang and inspired by [Spectral](https://github.com/stoplightio/spectral).

It's also compatible with existing [Spectral](https://github.com/stoplightio/spectral) rulesets.

## Install using [homebrew](https://brew.sh) tap

```
brew install daveshanley/vacuum/vacuum
```

## Install using [npm](https://npmjs.com)

```
npm i -g @quobix/vacuum
```

## Install using [yarn](https://yarnpkg.com/)

```
yarn global add @quobix/vacuum
```

## Install using curl

```
curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
```

## Install using [Docker](https://hub.docker.com/r/dshanley/vacuum)

The image is available at: https://hub.docker.com/r/dshanley/vacuum

```
docker pull dshanley/vacuum
```

To run, mount the current working dir to the container and use a relative path to your spec, like so

```
docker run --rm -v $PWD:/work:ro dshanley/vacuum lint <your-openapi-spec.yaml>
```
Alternatively, you can pull it from
[Github packages](https://github.com/daveshanley/vacuum/pkgs/container/vacuum).
To do that, replace `dshanley/vacuum` with `ghcr.io/daveshanley/vacuum` in the above commands.

## Run with Go

If you have go >= 1.16 installed, you can use `go run` to build and run it:

```
go run github.com/daveshanley/vacuum@latest lint <your-openapi-spec.yaml>
```

---


## Sponsors
If your company is using `vacuum`, please considering [supporting this project](https://github.com/sponsors/daveshanley),
like our _very kind_ sponsors:


<a href="https://speakeasyapi.dev/?utm_source=vacuum+repo&utm_medium=github+sponsorship">
<picture>
 <source media="(prefers-color-scheme: dark)" srcset=".github/sponsors/speakeasy-github-sponsor-dark.svg">
 <img alt="speakeasy'" src=".github/sponsors/speakeasy-github-sponsor-light.svg">
</picture>
</a>

[Speakeasy](https://speakeasyapi.dev/?utm_source=vacuum+repo&utm_medium=github+sponsorship)

<a href="https://scalar.com">
<picture>
 <source media="(prefers-color-scheme: dark)" srcset=".github/sponsors/scalar-dark.png">
 <img alt="scalar" src=".github/sponsors/scalar-light.png">
</picture>
</a>

[scalar](https://scalar.com)

---

## Come chat with us

Need help? Have a question? Want to share your work? [Join our discord](https://discord.gg/UAcUF78MQN) and
come say hi!

## Documentation

🔥 **New in** `v0.12+` 🔥 : **Core functions support JSON Path**.

Now all **core** functions return the **correct and accurate JSON path for each linting result**. Previously this was not possible
at all, but with some clever engineering, we have made it happen. It's a small thing, but with huge impact.

This feature has been available on the OpenAPI functions for some time, however core functions were without a comparison.
But no more! core functions have joined the party.

A new `--no-clip` flag is available on the `lint` command. This prevents message/path truncation.

---

`v0.11+`: Ignore Linting Errors/Violations.

v0.11 introduces the ability to ignore specific linting errors. This is useful for when you want to implement new 
rules to existing production APIs. In some cases, correcting the lint errors would result in a breaking change. 

Having a way to ignore these errors allows you to implement the new rules for new APIs while maintaining 
backwards compatibility for existing ones.

[Learn more about ignoring violations](https://quobix.com/vacuum/ignoring/)

---

`v0.10+` : **Quality release**.

v0.10 is a quality release, with a number of fixes and improvements to rule schemas, function names and more. 
vacuum now powers [The OpenAPI doctor](https://pb33f.io/doctor/). To enable correct ruleset management and automation
a number of functions have been renamed, interfaces have been upgraded and rule functions schemas are now accurate. 

This is a breaking change for anyone using vacuum as a library with custom rules. 

---

`v0.9+` : **Built in Language Server**.

A new command is available `language-server`. This starts vacuum as an LSP compatible language server. Run vacuum
in your favorite IDE and get linting and validation as you type, in realtime.

Will support any LSP compatible editor, like VSCode, Sublime, vim, etc.

[Install the VSCode extension](https://marketplace.visualstudio.com/items?itemName=pb33f.vacuum)
[Learn more about the language-server command](https://quobix.com/vacuum/commands/language-server/)

---

`v0.8+` : **OpenAPI Bundler**.

A new command is available `bundle` will bundle all external references for an OpenAPI file into a single file.

[Learn more about the bundle command](https://quobix.com/vacuum/commands/bundle/)

A new linting rule is available `oas-schema-check` will perform type checks and validation on all schemas in your
OpenAPI file. It's enabled by default in the recommended ruleset.

[oas-schema-check rule docs](https://quobix.com/vacuum/rules/schemas/oas-schema-check/)

---

`v0.7+` : **Hard Mode**.

Want to lint your spec with the most strict ruleset possible? Now you can! Use the `-z` / `--hard-mode` flag to enable

---

`v0.6+` : **Sharable / distributed rulesets** now available.

Want to share / extend / distribute your own rulesets? Now you can!

[Learn more about sharable rulesets](https://quobix.com/vacuum/rulesets/sharing/)

---

`v0.5+` : **Multi-file linting** now available for the `lint` command.

Want to lint multiple files at once? Now you can!

```shell
vacuum lint file1.json path/to/file2.yaml file3.json 
```

Want to suck in a ton of files? Use a **glob** pattern!

```shell
vacuum lint some/path/**/*.yaml 
```


---
`v0.3+`: [Custom JavaScript Functions](https://quobix.com/vacuum/api/custom-javascript-functions/) are now available out of the box.

Write custom functions in JavaScript and use them in any ruleset. No need
to compile golang code to extend vacuum anymore!

[Learn more about building custom JavaScript functions](https://quobix.com/vacuum/api/custom-javascript-functions/).


---
`v0.2+`: [OWASP API rules](https://quobix.com/vacuum/rules/owasp/) are now available out of the box.

[Learn more about enabling OWASP API rules](https://quobix.com/vacuum/rulesets/owasp/).

---

### [Quick Start Guide 🚀](https://quobix.com/vacuum/start)

See all the documentation at https://quobix.com/vacuum

- [Installing vacuum](https://quobix.com/vacuum/installing/)
- [About vacuum](https://quobix.com/vacuum/about/)
- [Why should you care?](https://quobix.com/vacuum/why/)
- [Concepts](https://quobix.com/vacuum/concepts/)
- [FAQ](https://quobix.com/vacuum/faq/)
- [CLI Commands](https://quobix.com/vacuum/commands/)
 - [lint](https://quobix.com/vacuum/commands/lint/)
 - [vacuum report](https://quobix.com/vacuum/commands/report/)
 - [dashboard](https://quobix.com/vacuum/commands/dashboard/)
 - [html-report](https://quobix.com/vacuum/commands/html-report/)
 - [bundle](https://quobix.com/vacuum/commands/bundle/)
 - [spectral-report](https://quobix.com/vacuum/commands/spectral-report/)
- [Developer API](https://quobix.com/vacuum/api/getting-started/)
 - [Using The Index](https://quobix.com/vacuum/api/spec-index/)
 - [RuleResultSet](https://quobix.com/vacuum/api/rule-resultset/)
 - [Loading a RuleSet](https://quobix.com/vacuum/api/loading-ruleset/)
 - [Linting Non-OpenAPI Files](https://quobix.com/vacuum/api/non-openapi/)
 - [Custom Golang Functions](https://quobix.com/vacuum/api/custom-functions/)
 - [Custom JavaScript Functions](https://quobix.com/vacuum/api/custom-javascript-functions/)
- [Rules](https://quobix.com/vacuum/rules/)
 - [Examples](https://quobix.com/vacuum/rules/examples/)
 - [Tags](https://quobix.com/vacuum/rules/tags/)
 - [Descriptions](https://quobix.com/vacuum/rules/descriptions/)
 - [Schemas](https://quobix.com/vacuum/rules/schemas/)
 - [Spec Information](https://quobix.com/vacuum/rules/information/)
 - [Operations & Paths](https://quobix.com/vacuum/rules/operations/)
 - [Validation](https://quobix.com/vacuum/rules/validation/)
 - [Security](https://quobix.com/vacuum/rules/security/)
 - [OWASP](https://quobix.com/vacuum/rules/owasp/)
- [Functions](https://quobix.com/vacuum/functions/)
 - [Core Functions](https://quobix.com/vacuum/functions/core/) 
 - [OpenAPI Functions](https://quobix.com/vacuum/functions/openapi/)
 - [OWASP Functions](https://quobix.com/vacuum/functions/owasp/)
- [Understanding RuleSets](https://quobix.com/vacuum/rulesets/understanding/)
 - [Sharing RuleSets](https://quobix.com/vacuum/rulesets/sharing/)
 - [All Rules](https://quobix.com/vacuum/rulesets/all/)
 - [No Rules](https://quobix.com/vacuum/rulesets/no-rules/)
 - [Recommended Rules](https://quobix.com/vacuum/rulesets/recommended/)
 - [Custom Rules](https://quobix.com/vacuum/rulesets/custom-rulesets/)

---

> **vacuum can suck all the lint of a 5mb OpenAPI spec in milliseconds.**

Designed to reliably lint OpenAPI specifications, **very, very quickly**. Including _very large_ ones. Spectral can be quite slow
when used as an API and does not scale for enterprise applications.

vacuum will tell you what is wrong with your spec, why, where and how to fix it. 

vacuum will work at scale and is designed as a CLI (with a web or console UI) and a library to be consumed in other applications.

### Dashboard

vacuum comes with an interactive dashboard (`vacuum dashboard <your-openapi-spec.yaml>`) allowing you to explore
rules and violations in a console, without having to scroll through thousands of results.

![vacuum dashboard](dashboard-screenshot.png)

### HTML Report

vacuum can generate an easy to navigate and understand HTML report. Like the dashboard
you can explore broken rules and violations, but in your browser.

No external dependencies, the HTML report will run completely offline.

![vacuum html-report](html-report-screenshot.png)

---

> **_Supports OpenAPI Version 2 (Swagger) and Version 3+_**

You can use either **YAML** or **JSON**, vacuum supports both formats.

## Using vacuum with pre-commit

Vacuum can be used with [pre-commit](https://pre-commit.com).

To do that, add to your `.pre-commit-config.yaml`:

```yaml
repos:
 - repo: https://github.com/daveshanley/vacuum
 rev: # a tag or a commit hash from this repo, see https://github.com/daveshanley/vacuum/releases
 hooks:
 - id: vacuum
```

See the [hook definition](./.pre-commit-hooks.yaml) here for details on what options the hook uses and what files it checks by default.

If no filenames or more than one filename in your repository matches the default `files` pattern in the hook definition,
the pattern needs to be overridden in your config so that it matches exactly one filename to lint at a time.
To lint multiple files, specify the hook multiple times with the appropriate overrides.

## Build an interactive HTML report 

```
./vacuum html-report <your-openapi-spec.yaml | vacuum-report.json.gz> <report-name.html>
```

You can replace `report-name.html` with your own choice of filename. Open the report
in your favorite browser and explore the results. 


## See full linting report 

```
./vacuum lint -d <your-openapi-spec.yaml>
```


## Lint multiple files at once

```
./vacuum lint -d <spec1.yaml> <spec2.yaml> <spec3.yaml>
```

## Lint multiple files using a glob pattern

```
./vacuum lint -d some/path/**/*.yaml
```

## See full linting report with inline code snippets

```
./vacuum lint -d -s <your-openapi-spec.yaml>
```

## See just the linting errors

```
./vacuum lint -d -e <your-openapi-spec.yaml>
```

## See just a specific category of report


```
./vacuum lint -d -c schemas <your-openapi-spec.yaml>
```

The options here are:

- `examples`
- `operations`
- `information`
- `descriptions`
- `schemas`
- `security`
- `tags`
- `validation`
- `owasp`

## Generate a Spectral compatible report

If you're already using Spectral JSON reports, and you want to use vacuum instead, use the `spectral-report` command

```
./vacuum spectral-report <your-openapi-spec.yaml> <report-output-name.json>
```

The report file name is _optional_. The default report output name is `vacuum-spectral-report.json`


## Generate a `vacuum report`

Vacuum reports are complete snapshots in time of a linting report for a specification. These reports can be 'replayed' 
back through vacuum. Use the `dashboard` or the `html-report` commands to 'replay' the report and explore the results
as they were when the report was generated.

```
./vacuum report -c <your-openapi-spec.yaml> <report-prefix>
```

The default name of the report will be `vacuum-report-MM-DD-YY-HH_MM_SS.json`. You can change the prefix by supplying
it as the second argument to the `report` command. 

Ideally, **you should compress the report using `-c`**. This shrinks down the size significantly. vacuum automatically
recognizes a compressed report file and will deal with it automatically when reading.

> When using compression, the file name will be `vacuum-report-MM-DD-YY-HH_MM_SS.json.gz`. vacuum uses gzip internally.

## Ignoring specific linting errors

You can ignore specific linting errors by providing an `--ignore-file` argument to the `lint` and `report` commands.

```
./vacuum lint --ignore-file <path-to-ignore-file.yaml> -d <your-openapi-spec.yaml>
```

```
./vacuum report --ignore-file <path-to-ignore-file.yaml> -c <your-openapi-spec.yaml> <report-prefix>
```

The ignore-file should point to a .yaml file that contains a list of errors to be ignored by vacuum. The structure of the
yaml file is as follows:

```
<rule-id-1>:
 - <json_path_to_error_or_warning_1>
 - <json_path_to_error_or_warning_2>
<rule-id-2>:
 - <json_path_to_error_or_warning_1>
 - <json_path_to_error_or_warning_2>
 ...
```

Ignoring errors is useful for when you want to implement new rules to existing production APIs. In some cases, 
correcting the lint errors would result in a breaking change. Having a way to ignore these errors allows you to implement
the new rules for new APIs while maintaining backwards compatibility for existing ones.

---

## Try out the dashboard

This is an early, but working console UI for vacuum. The code isn't great, it needs a lot of clean up, but
if you're interested in seeing how things are progressing, it's available.

```
./vacuum dashboard <your-openapi-spec.yaml | vacuum-report.json.gz>
```

---
## Supply your own Spectral compatible ruleset

If you're already using Spectral and you have your own [custom ruleset](https://meta.stoplight.io/docs/spectral/e5b9616d6d50c-custom-rulesets#custom-rulesets),
then you can use it with vacuum! 

The `lint`, `dashboard` and `spectral-report` commands all accept a `-r` or `--ruleset` flag, defining the path to your ruleset file.

### Here are some examples you can try

**_All rules turned off_**
```
./vacuum lint -r rulesets/examples/norules-ruleset.yaml <your-openapi-spec.yaml>
```

**_Only recommended rules_**
```
./vacuum lint -r rulesets/examples/recommended-ruleset.yaml <your-openapi-spec.yaml>
```

**_Enable specific rules only_**
```
./vacuum lint -r rulesets/examples/specific-ruleset.yaml <your-openapi-spec.yaml>
```

**_Custom rules_**
```
./vacuum lint -r rulesets/examples/custom-ruleset.yaml <your-openapi-spec.yaml>
```

**_All rules, all of them!**
```
./vacuum lint -r rulesets/examples/all-ruleset.yaml <your-openapi-spec.yaml>
```

---

## Configuration

### File
You can configure vacuum using a configuration file named `vacuum.conf.yaml`

By default, vacuum searches for this file in the following directories
1. Working directory
2. `$XDG_CONFIG_HOME`
3. `${HOME}/.config`

You can also specify a path to a file using the `--config` flag

Global flags are configured as top level nodes
```yaml
time: true
base: 'http://example.com'
...
```
Command specific flags are configured under a node with the commands name
```yaml
...
lint:
 silent: true
 ...
```

### Environmental variables

You can configure global vacuum flags using environmental variables in the form of: `VACUUM_<flag>`

If a flag, has a `-` in it, replace with `_`

> Logo gopher is modified, originally from [egonelbre](https://github.com/egonelbre/gophers)

vacuum

Automatically validates struct fields with tags.

Validate
========

A Go package to automatically validate fields with tags

[![GoDoc](https://godoc.org/github.com/mccoyst/validate?status.svg)](https://godoc.org/github.com/mccoyst/validate)

[![Build Status](https://api.travis-ci.org/mccoyst/validate.svg?branch=master)](http://travis-ci.org/mccoyst/validate)

[![Test Coverage](https://img.shields.io/badge/coverage-100.0%25-brightgreen.svg)](https://gocover.io/github.com/mccoyst/validate)

Is it good?
-----------
Yes.


validate

A linter to check that errors from external packages are wrapped.

# Wrapcheck

[![Go Report Card](https://goreportcard.com/badge/github.com/tomarrell/wrapcheck)](https://goreportcard.com/report/github.com/tomarrell/wrapcheck)
[![Tests](https://github.com/tomarrell/wrapcheck/actions/workflows/test.yaml/badge.svg)](https://github.com/tomarrell/wrapcheck/actions/workflows/test.yaml)

A simple Go linter to check that errors from external packages are wrapped
during return to help identify the error source during debugging.

> More detail in [this article](https://blog.tomarrell.com/post/introducing_wrapcheck_linter_for_go)

## Install

Go `>= v1.16`
```bash
$ go install github.com/tomarrell/wrapcheck/v2/cmd/wrapcheck@v2
```

Wrapcheck is also available as part of the golangci-lint meta linter. Docs and
usage instructions are available
[here](https://github.com/golangci/golangci-lint). When used with golangci-lint,
configuration is integrated with the `.golangci.yaml` file.

## Configuration

You can configure wrapcheck by using a `.wrapcheck.yaml` file in either the
local directory, or in your home directory.

```yaml
# An array of strings which specify substrings of signatures to ignore. If this
# set, it will override the default set of ignored signatures. You can find the
# default set at the top of ./wrapcheck/wrapcheck.go.
ignoreSigs:
- .Errorf(
- errors.New(
- errors.Unwrap(
- errors.Join(
- .Wrap(
- .Wrapf(
- .WithMessage(
- .WithMessagef(
- .WithStack(

# An array of strings which specify regular expressions of signatures to ignore.
# This is similar to the ignoreSigs configuration above, but gives slightly more
# flexibility.
ignoreSigRegexps:
- \.New.*Error\(

# An array of glob patterns which, if any match the package of the function
# returning the error, will skip wrapcheck analysis for this error. This is
# useful for broadly ignoring packages and/or subpackages from wrapcheck
# analysis. There are no defaults for this value.
ignorePackageGlobs:
- encoding/*
- github.com/pkg/*

# ignoreInterfaceRegexps defines a list of regular expressions which, if matched
# to a underlying interface name, will ignore unwrapped errors returned from a
# function whose call is defined on the given interface.
ignoreInterfaceRegexps:
- ^(?i)c(?-i)ach(ing|e)
```

## Usage

To lint all the packages in a program:

```bash
$ wrapcheck ./...
```

## Testing

This linter is tested using `analysistest`, you can view all the test cases
under the [testdata](./wrapcheck/testdata) directory.

## TLDR

If you've ever been debugging your Go program, and you've seen an error like
this pop up in your logs.

```log
time="2020-08-04T11:36:27+02:00" level=error error="sql: error no rows"
```

Then you know exactly how painful it can be to hunt down the cause when you have
many methods which looks just like the following:

```go
func (db *DB) getUserByID(userID string) (User, error) {
	sql := `SELECT * FROM user WHERE id = $1;`

	var u User
	if err := db.conn.Get(&u, sql, userID); err != nil {
		return User{}, err // wrapcheck error: error returned from external package is unwrapped
	}

	return u, nil
}

func (db *DB) getItemByID(itemID string) (Item, error) {
	sql := `SELECT * FROM item WHERE id = $1;`

	var i Item
	if err := db.conn.Get(&i, sql, itemID); err != nil {
		return Item{}, err // wrapcheck error: error returned from external package is unwrapped
	}

	return i, nil
}
```

The problem here is that multiple method calls into the `sql` package can return
the same error. Therefore, it helps to establish a trace point at the point
where error handing across package boundaries occurs.

To resolve this, simply wrap the error returned by the `db.Conn.Get()` call.

```go
func (db *DB) getUserByID(userID string) (User, error) {
	sql := `SELECT * FROM user WHERE id = $1;`

	var u User
	if err := db.Conn.Get(&u, sql, userID); err != nil {
		return User{}, fmt.Errorf("failed to get user by ID: %v", err) // No error!
	}

	return u, nil
}

func (db *DB) getItemByID(itemID string) (Item, error) {
	sql := `SELECT * FROM item WHERE id = $1;`

	var i Item
	if err := db.Conn.Get(&i, sql, itemID); err != nil {
		return Item{}, fmt.Errorf("failed to get item by ID: %v", err) // No error!
	}

	return i, nil
}
```

Now, your logs will be more descriptive, and allow you to easily locate the
source of your errors.

```log
time="2020-08-04T11:36:27+02:00" level=error error="failed to get user by ID: sql: error no rows"
```

A further step would be to enforce adding stack traces to your errors instead
using
[`errors.WithStack()`](https://pkg.go.dev/github.com/pkg/errors?tab=doc#WithStack)
however, enforcing this is out of scope for this linter for now.

## Why?

Errors in Go are simple values. They contain no more information about than the
minimum to satisfy the interface:

```go
type Error interface {
  Error() string
}
```

This is a fantastic feature, but can also be a limitation. Specifically when you
are attempting to identify the source of an error in your program.

As of Go 1.13, error wrapping using `fmt.Errorf(...)` is the recommend way to
compose errors in Go in order to add additional information.

Errors generated by your own code are usually predictable. However, when you
have a few frequently used libraries (think `sqlx` for example), you may run
into the dilemma of identifying exactly where in your program these errors are
caused.

In other words, you want a call stack.

This is especially apparent if you are a diligent Gopher and always hand your
errors back up the call stack, logging at the top level.

So how can we solve this?

## Solution

Wrapping errors at the call site.

When we call into external libraries which may return an error, we can wrap the
error to add additional information about the call site.

e.g.

```go
...

func (db *DB) createUser(name, email, city string) error {
  sql := `INSERT INTO customer (name, email, city) VALUES ($1, $2, $3);`

  if _, err := tx.Exec(sql, name, email, city); err != nil {
    // %v verb preferred to prevent error becoming part of external API
    return fmt.Errorf("failed to insert user: %v", err)
  }

  return nil
}

...
```

This solution allows you to add context which will be handed to the caller,
making identifying the source easier during debugging.

## Contributing

As with most static analysis tools, this linter will likely miss some obscure
cases. If you come across a case which you think should be covered and isn't,
please file an issue including a minimum reproducible example of the case.

## License

This project is licensed under the MIT license. See the [LICENSE](./LICENSE) file for more
details.



The Best Go Libraries For Code Analysis (22)