DOCSEARCHbyAlgolia
Submit Docs

forbidigo

repository·master·Indexed 41 days ago

https://github.com/ashanbrown/forbidigo

A Go linter that detects forbidden code patterns in Go source files using literal string matching or semantic type analysis. It can be used as a standalone tool or as part of golangci-lint. It supports regular expressions, JSON/YAML configuration for custom error messages, and an `-analyze_types` flag to expand expressions for more accurate matching regardless of package aliases.

Tokens
1.3K
Snippets
5
Records
7
Agent score
2%

What's inside forbidigo

  1. Configure complex patterns using JSON or YAML

    master

    While simple regular expressions work for literal matches, you can provide more complex patterns by passing a JSON or YAML string. This allows you to attach custom error messages to matches.

    The pattern object contains:

    • msg: An additional comment added to the error message when a match occurs.
    • p: The regular expression to match against the source code (or the expanded expression if analyze_types is enabled).
    • pkg: A regular expression for the full package import path (only supported when analyze_types is enabled).

    To distinguish these from standard regex patterns, the string must start with { or contain line breaks.

    Examples

    JSON format:

    {p: "^fmt\\.Println$", msg: "do not write to stdout"}

    YAML format:

    p: ^fmt\.Println$
msg: do not write to stdout

    Inline JSON-like format:

    {p: ^fmt\.Println$, msg: do not write to stdout}

  2. Use forbidigo via CLI

    master

    The basic CLI syntax for forbidigo is:

    forbidigo [flags...] patterns... -- packages...

    Default Behavior

    • If no patterns are specified, it uses the default pattern ^(fmt\.Print.*|print|println)$ to catch debug statements.
    • By default, Godoc examples are excluded from checking.
    • By default, patterns match against the literal source code text.

    Advanced Type Analysis Mode

    To handle cases where packages are imported with aliases (e.g., import fmt2 "fmt"), use the -analyze_types flag. This mode uses type information to expand expressions before matching.

    Expansion Rules for Type Analysis:

    • Package/Type/Field: Expressions are expanded to <package name>.<type name>.<field or method name>. Note that <package name> is the name declared in the package statement, not necessarily the last part of the import path.
    • Pointers: Pointers are treated as the type they point to.
    • Type Aliases: If a type is an alias, the name of the underlying package is used.
    • Dot Imports: If an identifier is imported via import ., it is matched both literally and as an expanded package-qualified name.
    • Limitations:
      • Embedding: References to inherited fields/methods are resolved using the outer struct as the type.
      • Interfaces: Method calls on interfaces resolve to the interface type, not the underlying implementation.

    Note: Enabling -analyze_types may impact performance due to the additional analysis required.

    forbidigo -analyze_types "^fmt\.Print$" -- ./...

  4. Ignore issues in forbidigo

    master

    Standalone Mode

    In standalone mode, you can ignore a specific issue by adding the //permit directive on the line containing the match.

    golangci-lint Mode

    When running forbidigo as part of golangci-lint, the //permit directive is disabled. You must use the standard //nolint directive to ignore issues, consistent with other golangci-lint linters.

  5. Reference forbidigo CLI flags

    master

    The following flags are available to control forbidigo behavior:

    FlagDefaultDescription
    -set_exit_statusfalseSet exit status to 1 if any issues are found.
    -exclude_godoc_examplestrueControls whether godoc examples are identified and excluded.
    -teststrueControls whether tests are included.
    -analyze_typesfalseReplace literal source code with expanded type information before matching.

  6. Configure forbidigo CLI flags

    master

    The following flags are available when running the forbidigo CLI:

    FlagDefaultDescription
    --set_exit_statusfalseSet exit status to 1 if any issues are found
    --teststrueInclude tests in the analysis
    --exclude_godoc_examplestrueExclude code in godoc examples
    --analyze_typesfalseReplace the literal source code based on the semantic of the code before matching against patterns

    Note: --analyze_types requires additional package loading modes (packages.NeedTypesInfo and packages.NeedDeps) to function.

    # Example: Run with type analysis and exit with error code 1 if issues are found
forbidigo --analyze_types --set_exit_status .

  7. Use the forbidigo CLI

    master

    The forbidigo CLI tool scans Go source code for forbidden patterns. You can provide specific patterns as arguments, or use the default patterns if none are provided. To separate patterns from the target packages, use the -- delimiter.

    Basic Usage: forbidigo [patterns] [packages]

    Usage with delimiter: forbidigo [patterns] -- [packages]

    If no patterns are provided, the tool uses forbidigo.DefaultPatterns().

    # Run with default patterns on current directory
forbidigo .

# Run with specific patterns on specific packages
forbidigo "pattern1" "pattern2" -- ./pkg/...