DOCSEARCHbyAlgolia
Submit Docs

goconst

repository·master·Indexed 43 days ago

https://github.com/jgautheron/goconst

A static analysis tool for Go that identifies repeated string and number literals that are candidates for replacement by constants. It supports exact literal matching, Unicode-aware length filtering, constant expression evaluation, and programmatic integration via the Run and RunWithConfig functions.

Tokens
3.8K
Snippets
8
Records
11
Agent score
46%

What's inside goconst

  1. How goconst works

    master

    goconst analyzes Go source code to detect string and (optionally) number literals that appear multiple times.

    Key behaviors:

    • Exact literal matching: It compares complete, unquoted literal values. It does not detect repeated substrings within larger strings.
    • Constant handling: By default, const declarations are skipped. To include them, use -match-constant (to match strings against existing constants) or -find-duplicates (to find constants sharing the same value).
    • Unicode support: String length is measured in runes rather than bytes, ensuring multi-byte Unicode characters are handled correctly when using -min-length.

  3. Use the goconst CLI to find repeated strings

    master

    goconst is a static analysis tool used to find repeated string literals (and optionally numbers) in Go code that could be replaced by constants. It scans directories and reports occurrences, matching existing constants, or finding duplicate constant values.

    Basic Usage

    goconst ./...

    Common Examples

    • Exclude specific files/patterns:
      goconst -ignore "yacc|\.pb\." $GOPATH/src/github.com/cockroachdb/cockroach/...
    • JSON output for automation:
      goconst -min-occurrences 3 -output json $GOPATH/src/github.com/cockroachdb/cockroach
    • Search for duplicated numbers within a range:
      goconst -numbers -min 60 -max 512 .
    • Ignore strings used in specific function calls (e.g., logging):
      goconst -ignore-calls slog.Info,slog.Warn,fmt.Errorf ./...
    • Match existing constant expressions:
      goconst -eval-const-expr -match-constant .
    goconst ./...

  4. Examples of goconst usage

    master

    Common usage patterns for goconst:

    • Basic scan: goconst ./...
    • Ignore specific patterns: goconst -ignore "yacc|\.pb\." <directory>
    • JSON output with occurrence threshold: goconst -min-occurrences 3 -output json <directory>
    • Find duplicate numbers in a range: goconst -numbers -min 60 -max 512 .
    • Match against existing constant expressions: goconst -eval-const-expr -match-constant .
    • Ignore strings in logging/error calls: goconst -ignore-calls slog.Info,slog.Warn,fmt.Errorf ./...
    # Basic scan
goconst ./...

# Ignore specific patterns
goconst -ignore "yacc|\.pb." $GOPATH/src/github.com/cockroachdb/cockroach/...

# JSON output with occurrence threshold
goconst -min-occurrences 3 -output json $GOPATH/src/github.com/cockroachdb/cockroach

# Find duplicate numbers in a range
goconst -numbers -min 60 -max 512 .

# Match against existing constant expressions
goconst -eval-const-expr -match-constant .

# Ignore strings in logging/error calls
goconst -ignore-calls slog.Info,slog.Warn,fmt.Errorf ./...

  5. Configure the goconst analyzer with Config

    master

    The Config struct allows you to fine-tune the detection logic. Key configuration options include:

    • IgnoreStrings []string: A list of regular expressions to filter out specific strings.
    • IgnoreTests bool: If true, test files (*_test.go) are excluded from analysis.
    • MatchWithConstants bool: Enables matching found strings against existing defined constants.
    • MinStringLength int: Minimum length for a string to be reported.
    • MinOccurrences int: Minimum number of occurrences required to report a finding.
    • ParseNumbers bool: Enables detection of duplicated numeric literals.
    • NumberMin int / NumberMax int: Range limits for reported number matches.
    • ExcludeTypes map[Type]bool: Allows excluding specific context types.
    • FindDuplicates bool: Enables finding constants whose values match existing constants in other packages.
    • EvalConstExpressions bool: Enables evaluation of constant expressions (e.g., Prefix + "suffix").
    • IgnoreFunctions []string: List of function names whose string arguments should be ignored (e.g., "println" or "slog.Info").
    • IgnoreMapKeys bool: If true, ignores string literals used as keys in map literals.
    cfg := &goconst.Config{
	IgnoreStrings:      []string{`^DEBUG_`}, // Regex pattern
	MinStringLength:     4,
	MinOccurrences:     2,
	MatchWithConstants: true,
	ParseNumbers:       true,
	IgnoreFunctions:    []string{"fmt.Printf", "slog.Info"},
	IgnoreMapKeys:      true,
}

  6. Configure goconst output formats

    master

    The -output flag determines how the analysis results are displayed.

    • text (default): Prints human-readable information about repeated strings and matching constants. If -grouped is also set, it prints a single line per match instead of one line per occurrence.
    • json: Outputs a JSON object containing two keys: strings (the detected repeated strings and their positions) and constants (the matching constants found).

    Example JSON structure:

    {
  "strings": { ... },
  "constants": { ... }
}

  7. Use goconst CLI flags

    master

    The goconst command accepts several flags to filter results and change detection behavior.

    Filtering and Ignoring:

    • -ignore <regex>: Exclude files matching the regular expression.
    • -ignore-strings <regex>: Exclude strings matching the regular expression.
    • -ignore-tests: Exclude tests from the search (enabled by default).
    • -ignore-calls <comma-separated-list>: Ignore string literals used as arguments in specific function calls (e.g., slog.Info,fmt.Errorf).
    • -ignore-composite-literals: Ignore string literals inside composite literals.
    • -ignore-map-keys: Ignore string literals used as map keys.

    Detection Criteria:

    • -min-occurrences <n>: Report literals appearing at least n times (default: 2).
    • -min-length <n>: Only report literals with a minimum length of n runes (default: 3).
    • -numbers: Search for duplicated numbers in addition to strings.
    • -min <n> / -max <n>: Set minimum/maximum values (only works with -numbers).
    • -eval-const-expr: Enable evaluation of constant expressions (e.g., Prefix + "suffix").

    Constant Matching:

    • -match-constant: Look for existing constants matching the detected strings.
    • -find-duplicates: Look for constants that share identical values.

    Output and Exit Status:

    • -output <text|json>: Set output format.
    • -grouped: Print a single line per match (only works with -output text).
    • -set-exit-status: Set exit status to 2 if any issues are found.
    Usage: goconst ARGS <directory> [<directory>...]

Flags:
  -ignore                     exclude files matching the given regular expression
  -ignore-strings             exclude strings matching the given regular expression
  -ignore-tests               exclude tests from the search (default: true)
  -min-occurrences            report from how many occurrences (default: 2)
  -min-length                 only report strings with the minimum given length (default: 3)
  -match-constant             look for existing constants matching the strings
  -find-duplicates            look for constants with identical values
  -eval-const-expr            enable evaluation of constant expressions (e.g., Prefix + "suffix")
  -ignore-calls               ignore string literals in calls to these functions (comma separated)
  -ignore-composite-literals  ignore string literals inside composite literals
  -ignore-map-keys            ignore string literals used as map keys
  -numbers                    search also for duplicated numbers
  -min                        minimum value, only works with -numbers
  -max                        maximum value, only works with -numbers
  -output                     output formatting (text or json)
  -set-exit-status            Set exit status to 2 if any issues are found
  -grouped                    print single line per match, only works with -output text

  8. Run goconst analysis programmatically

    master

    You can integrate goconst into your own Go tools by calling Run or RunWithConfig. These functions analyze a set of AST files for duplicated strings, numbers, or constants based on a provided Config object.

    Both functions require the AST files, a token.FileSet, and types.Info (from the go/types package) to perform accurate analysis, such as constant expression evaluation and type-aware matching.

    import (
	"go/ast"
	"go/token"
	"go/types"
	"github.com/jgautheron/jgautheron/goconst"
)

// ... setup fset, files, and typeInfo ...

cfg := &goconst.Config{
	MinStringLength: 5,
	MinOccurrences: 2,
	ParseNumbers:    true,
}

issues, err := goconst.Run(files, fset, typeInfo, cfg)
if err != nil {
	// handle error
}

for _, issue := range issues {
	// process issue
}

  9. Create a parser with multiple ignore patterns

    master

    If you need to initialize a parser with a specific set of ignore patterns, use NewWithIgnorePatterns. This function is a convenience wrapper that joins multiple regex patterns into a single OR-joined pattern for the underlying engine.

    // Example of creating a parser with multiple regex patterns for ignored strings
parser := goconst.NewWithIgnorePatterns(
	"/path/to/pkg", // path
	"",             // ignore
	[]string{"pattern1", "pattern2"}, // ignoreStrings
	true,            // ignoreTests
	true,            // matchConstant
	true,            // numbers
	false,           // findDuplicates
	true,            // evalConstExpressions
	0,               // numberMin
	0,               // numberMax
	5,               // minLength
	2,               // minOccurrences
	nil,             // excludeTypes
)

  10. goconst CLI flag reference

    master

    The following flags are available to configure the goconst analysis:

    FlagDefaultDescription
    -ignore""Exclude files matching the given regular expression
    -ignore-strings""Exclude strings matching the given regular expressions (comma separated)
    -ignore-teststrueExclude tests from the search
    -min-occurrences2Report from how many occurrences
    -min-length3Only report strings with the minimum given length
    -match-constantfalseLook for existing constants matching the strings
    -find-duplicatesfalseLook for constants with identical values
    -eval-const-exprfalseEnable evaluation of constant expressions (e.g., Prefix + "suffix")
    -numbersfalseSearch also for duplicated numbers
    -min0Minimum value (only works with -numbers)
    -max0Maximum value (only works with -numbers)
    -output"text"Output formatting (text or json)
    -set-exit-statusfalseSet exit status to 2 if any issues are found
    -groupedfalsePrint single line per match (only works with -output text)
    -ignore-calls""Ignore string literals in calls to these functions (comma separated, e.g. slog.Info,fmt.Errorf)
    -ignore-composite-literalsfalseIgnore string literals inside composite literals
    -ignore-map-keysfalseIgnore string literals used as map keys

  11. Understand the Issue struct

    master

    An Issue represents a single finding of a duplicated string, number, or constant. It contains the following fields:

    • Pos: The token.Position where the issue was found.
    • OccurrencesCount: How many times the value occurs within its scope (test files and non-test files are scoped independently).
    • Str: The actual string or value that was duplicated.
    • MatchingConst: The name of a constant that matches this string (if MatchWithConstants is enabled).
    • DuplicateConst: The name of the constant that is a duplicate (if FindDuplicates is enabled).
    • DuplicatePos: The token.Position of the original constant that was duplicated.
    type Issue struct {
	Pos              token.Position
	OccurrencesCount int
	Str              string
	MatchingConst    string
	DuplicateConst   string
	DuplicatePos     token.Position
}