ktn-linter

module

v0.107.5 Latest Latest Go to latest Published: Feb 27, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/kodflow/ktn-linter

Links

Open Source Insights

README ¶

KTN-Linter

Personal Go linter enforcing strict programming standards beyond golangci-lint and staticcheck. 178 rules covering naming, structure, testing, performance, and modern Go idioms.

Strict rule: 0 issues = 0 issues (even INFO). STOP and fix immediately.

Installation

Universal Installation (Recommended)

curl -sSL https://raw.githubusercontent.com/kodflow/ktn-linter/main/install.sh | bash

The script downloads the binary from GitHub releases (linux/darwin, amd64/arm64), installs to /usr/local/bin or ~/.local/bin, and optionally configures golangci-lint.

Installation from Source

git clone https://github.com/kodflow/ktn-linter
cd ktn-linter
make build

Usage

ktn-linter lint ./...                              # Lint the entire project
ktn-linter lint --simple ./pkg/...                 # Simplified format
ktn-linter lint --fix ./...                        # Apply safe modernize fixes
ktn-linter lint --config .ktn-linter.yaml ./...    # Use a config file
ktn-linter rules --format=markdown                 # Display all rules

Configuration

KTN-Linter can be configured via .ktn-linter.yaml:

version: 1

exclude:
  - "**/testdata/**"
  - "**/*_generated.go"
  - "vendor/**"

rules:
  KTN-FUNC-MAXSTMT:
    threshold: 50
  KTN-FUNC-CYCLO:
    threshold: 15
  KTN-COMMENT-LINELEN:
    enabled: false

Configurable thresholds:

Rule	Parameter	Default
KTN-COMMENT-LINELEN	maxCommentLength	80
KTN-COMMENT-PKGDOC	minPackageCommentLength	3
KTN-COMMENT-STRUCT	minStructDocLines	2
KTN-FUNC-MAXSTMT	maxFunctionLength	35
KTN-FUNC-MAXPARAM	maxParameters	5
KTN-FUNC-NAKEDRET	maxReturnValues	3
KTN-FUNC-CYCLO	maxCyclomaticComplexity	8
KTN-FUNC-NAMERET	maxNestedDepth	4
KTN-VAR-MAKEAPPEND	maxScopeLines	50
KTN-VAR-HOTLOOP	maxLineLength	120
KTN-VAR-GROUP	maxDeclarations	10

Development

make test      # Tests + coverage (generates COVERAGE.MD)
make lint      # Runs the KTN linter on itself
make validate  # Validates all testdata good.go/bad.go
make build     # Compiles to builds/
make fmt       # Formats Go code
make help      # All targets

See COVERAGE.MD for the detailed coverage report.

Rules (178 total)

KTN-API (1 rule)

Code	Severity	Description
KTN-API-MINIF	WARNING	Minimal interfaces on consumer side for external dependencies

KTN-COMMENT (7 rules)

Code	Severity	Description
KTN-COMMENT-LINELEN	INFO	Inline comments too long (>80 characters)
KTN-COMMENT-PKGDOC	WARNING	Descriptive comment before `package`
KTN-COMMENT-CONST	WARNING	Required comment for constants
KTN-COMMENT-VAR	WARNING	Required comment for package var
KTN-COMMENT-STRUCT	WARNING	Required documentation for struct (>=2 lines)
KTN-COMMENT-FUNC	WARNING	Function documentation (Params/Returns)
KTN-COMMENT-BLOCK	WARNING	Comments on branches/returns/logic

KTN-CONST (6 rules)

Code	Severity	Description
KTN-CONST-TYPED	ERROR	Explicit type required
KTN-CONST-ORDER	INFO	Grouping and placement before var
KTN-CONST-CAMEL	INFO	CamelCase naming (no underscores)
KTN-CONST-MINLEN	WARNING	Min length 2 characters
KTN-CONST-MAXLEN	INFO	Max length 30 characters
KTN-CONST-SHADOW	INFO	Must not shadow built-in identifiers

KTN-ERROR (3 rules)

Code	Severity	Description
KTN-ERROR-ASTYPE	INFO	Prefer errors.AsTypeT (Go 1.26+)
KTN-ERROR-SENTINEL	WARNING	errors.New() should be package-level sentinel
KTN-ERROR-WRAP	WARNING	fmt.Errorf() should wrap errors with %w

KTN-FUNC (20 rules)

Code	Severity	Description
KTN-FUNC-ERRLAST	ERROR	Error always in last return position
KTN-FUNC-CTXFIRST	ERROR	Context always as first parameter
KTN-FUNC-EARLYRET	ERROR	Avoid else after return/continue/break
KTN-FUNC-DEADCODE	ERROR	Unused private functions (dead code)
KTN-FUNC-CYCLO	ERROR	Max cyclomatic complexity 8
KTN-FUNC-MAXLOC	ERROR	Max 50 lines of code (LOC)
KTN-FUNC-MAXSTMT	WARNING	Max 35 statements per function
KTN-FUNC-MAXPARAM	WARNING	Max 5 parameters per function
KTN-FUNC-PUREGET	WARNING	No side effects in getters
KTN-FUNC-UNUSEDARG	WARNING	Unused parameters prefixed with _
KTN-FUNC-BLANKPARAM	WARNING	Blank _ in params must be interface-required
KTN-FUNC-NOMAGIC	INFO	No magic numbers (use named constants)
KTN-FUNC-NAKEDRET	INFO	No naked returns (except <5 lines)
KTN-FUNC-NAMERET	INFO	Named returns for >3 return values
KTN-FUNC-GROUPARG	INFO	Group parameters of same type
KTN-FUNC-MINMAX	INFO	Prefer min/max builtins (Go 1.21+)
KTN-FUNC-USECLEAR	INFO	Use clear() builtin (Go 1.21+)
KTN-FUNC-RANGEINT	INFO	Use range N (Go 1.22+)
KTN-FUNC-ERRFMT	INFO	Error message format (lowercase, no period)
KTN-FUNC-NOINIT	WARNING	Avoid init() functions

KTN-GENERIC (5 rules)

Code	Severity	Description
KTN-GENERIC-CMPEQ	ERROR	Comparable constraint required for == and !=
KTN-GENERIC-ORDERED	ERROR	cmp.Ordered constraint required for <, >, +, -, *, /, %
KTN-GENERIC-NOANY	WARNING	Unnecessary generics on interface types
KTN-GENERIC-USECMP	WARNING	golang.org/x/exp/constraints deprecated -> cmp
KTN-GENERIC-SHADOW	WARNING	Type params must not shadow predeclared identifiers

KTN-GOROUTINE (6 rules)

Code	Severity	Description
KTN-GOROUTINE-CTXCANCEL	WARNING	context.With*() without immediate defer cancel()
KTN-GOROUTINE-DEFER	WARNING	Immediate defer after resource acquisition
KTN-GOROUTINE-FIREFORGET	WARNING	Goroutine launched without synchronization
KTN-GOROUTINE-LIFECYCLE	WARNING	Missing goroutine documentation
KTN-GOROUTINE-SELECT	WARNING	Infinite loop goroutine without exit mechanism
KTN-GOROUTINE-TIMEAFTER	WARNING	time.After() in select inside loop (timer leak)

KTN-INTERFACE (3 rules)

Code	Severity	Description
KTN-INTERFACE-UNUSED	WARNING	Unused private interface
KTN-INTERFACE-ERNAME	INFO	-er convention for single-method interfaces
KTN-INTERFACE-ANYUSE	INFO	Excessive use of interface{}/any

KTN-ITER (5 rules)

Code	Severity	Description
KTN-ITER-SIGNATURE	INFO	Invalid iterator signature
KTN-ITER-YIELD	INFO	Ignored yield return
KTN-ITER-MAPKEYS	INFO	Use maps.Keys/Values iterators
KTN-ITER-COLLECT	INFO	Use slices.Collect for iterators
KTN-ITER-PULLSTOP	INFO	iter.Pull must have defer stop()

KTN-RECEIVER (4 rules)

Code	Severity	Description
KTN-RECEIVER-MIXPTR	ERROR	Mixed receivers (pointer/value) on same type
KTN-RECEIVER-GENERIC	WARNING	Inconsistent generic receivers
KTN-RECEIVER-PTRMAP	WARNING	Unnecessary pointer to map/func/chan
KTN-RECEIVER-NAME	INFO	Receiver name 1-2 chars, not this/self/me

KTN-STRUCT (10 rules)

Code	Severity	Description
KTN-STRUCT-CTOR	WARNING	NewX() constructor required
KTN-STRUCT-NOGET	WARNING	No Get prefix for getters
KTN-STRUCT-RECVTYPE	WARNING	Receiver type consistency (pointer vs value)
KTN-STRUCT-RECVNAME	WARNING	Receiver name consistency (1-2 letters)
KTN-STRUCT-ACCESSOR	INFO	Getters/setters convention: Field() and SetField()
KTN-STRUCT-ONEFILE	INFO	One Go file per struct (DTOs can be grouped)
KTN-STRUCT-PUBFIRST	INFO	Exported fields before private fields
KTN-STRUCT-PRIVTAG	INFO	No serialization tags on private fields
KTN-STRUCT-JSONTAG	INFO	DTO exported fields must have json/xml tags
KTN-STRUCT-DTOTAG	INFO	DTO fields must have dto tag

KTN-SWITCH (1 rule)

Code	Severity	Description
KTN-SWITCH-EXHAUSTIVE	WARNING	Switch on enum types must cover all values

KTN-TEST (20 rules)

Code	Severity	Description
KTN-TEST-SUFFIX	ERROR	Test files must end with _internal/_external_test.go
KTN-TEST-SETENV	ERROR	t.Setenv/t.Chdir forbidden with t.Parallel
KTN-TEST-HASGO	WARNING	Orphan test file (no source file)
KTN-TEST-COVERAGE	WARNING	Test coverage for public functions
KTN-TEST-TABLE	WARNING	Table-driven pattern required
KTN-TEST-NOSKIP	WARNING	t.Skip() forbidden
KTN-TEST-SPLIT	WARNING	1:1 pattern for test/source files
KTN-TEST-EXTPUB	WARNING	Public tests only in _external_test.go
KTN-TEST-INTPRIV	WARNING	Private tests only in _internal_test.go
KTN-TEST-PKGNAME	WARNING	Package convention (white-box/black-box)
KTN-TEST-ASSERT	WARNING	Tests must contain assertions
KTN-TEST-ERRCASES	WARNING	Tests must cover error cases
KTN-TEST-SUBPARALLEL	WARNING	Subtests should have t.Parallel when parent does
KTN-TEST-CLEANUP	WARNING	Use t.Cleanup instead of defer with parallel subtests
KTN-TEST-TMPDIR	INFO	Prefer t.TempDir() over os.TempDir()
KTN-TEST-CHDIR	INFO	Prefer t.Chdir() over os.Chdir()
KTN-TEST-TMPFILE	INFO	Use t.TempDir() in os.CreateTemp
KTN-TEST-MKDIR	INFO	Use t.TempDir() instead of os.MkdirTemp()
KTN-TEST-CASECNT	INFO	Number of cases vs cyclomatic complexity
KTN-TEST-PARALLELPOS	INFO	t.Parallel should be first statement

KTN-VAR (40 rules)

Code	Severity	Description
KTN-VAR-CAMEL	ERROR	Required camelCase naming
KTN-VAR-SHADOW	ERROR	Variable shadowing detection
KTN-VAR-MUTEXCOPY	ERROR	Mutex copies (sync.Mutex, sync.RWMutex)
KTN-VAR-EXPLICIT	WARNING	Explicit type required for package var
KTN-VAR-ORDER	WARNING	Ordered declarations (const before var)
KTN-VAR-MINLEN	WARNING	Min variable length (scope-aware)
KTN-VAR-MAXLEN	WARNING	Max length 30 characters
KTN-VAR-HOTLOOP	WARNING	Avoid allocations in hot loops
KTN-VAR-RECVCONS	WARNING	Receiver consistency (pointer vs value)
KTN-VAR-PTRINTF	WARNING	Avoid pointer to interface
KTN-VAR-WEAKRAND	WARNING	crypto/rand for sensitive data
KTN-VAR-TYPEASSERT	WARNING	Unchecked type assertion (use comma-ok)
KTN-VAR-SHORTDECL	INFO	:= vs var (zero-value aware)
KTN-VAR-SLICECAP	INFO	Preallocate slices with known capacity
KTN-VAR-MAKEAPPEND	INFO	Avoid make([]T, length) with append
KTN-VAR-GROW	INFO	Preallocate bytes.Buffer with Grow
KTN-VAR-STRBUILDER	INFO	Use strings.Builder for concatenations
KTN-VAR-BIGSTRUCT	INFO	Pointers for structs >64 bytes as parameter
KTN-VAR-SYNCPOOL	INFO	sync.Pool for repeated buffers
KTN-VAR-STRCONV	INFO	Avoid repeated string() conversions
KTN-VAR-GROUP	INFO	Group in a single var() block
KTN-VAR-MAPCAP	INFO	Preallocate maps with known capacity
KTN-VAR-ARRAY	INFO	Use [N]T instead of make([]T, N) <=64 bytes
KTN-VAR-NILSLICE	INFO	Prefer nil slice to empty slice
KTN-VAR-USEANY	INFO	any vs interface{} (Go 1.18+)
KTN-VAR-USECLEAR	INFO	Use clear() built-in (Go 1.21+)
KTN-VAR-USEMINMAX	INFO	Use min()/max() built-in (Go 1.21+)
KTN-VAR-RANGEINT	INFO	range over integer (Go 1.22+)
KTN-VAR-LOOPVAR	INFO	Loop var copy obsolete (Go 1.22+)
KTN-VAR-SLICEGROW	INFO	slices.Grow instead of make+copy (Go 1.21+)
KTN-VAR-SLICECLONE	INFO	slices.Clone instead of make+copy (Go 1.21+)
KTN-VAR-MAPCLONE	INFO	maps.Clone instead of manual loop (Go 1.21+)
KTN-VAR-CMPOR	INFO	cmp.Or for default values (Go 1.22+)
KTN-VAR-WGGO	INFO	WaitGroup.Go (Go 1.25+)
KTN-VAR-CONTAINS	INFO	slices.Contains instead of loop (Go 1.21+)
KTN-VAR-INDEX	INFO	slices.Index instead of loop (Go 1.21+)
KTN-VAR-COLLECTKEYS	INFO	maps.Keys/Values iterators (Go 1.23+)
KTN-VAR-EXTRACTCONST	INFO	Extract repeated literals to constants
KTN-VAR-NEWEXPR	INFO	Use new(expr) instead of v := expr; &v (Go 1.26+)
KTN-VAR-CRYPTONIL	INFO	Pass nil to crypto APIs instead of rand.Reader (Go 1.26+)
KTN-VAR-REFLECTITER	INFO	Use reflect Fields()/Methods() iterators (Go 1.26+)

KTN-GOVET (27 active / 28 total)

Official go vet analyzers wrapped with KTN-GOVET- prefix: appends, assign, atomic, bools, copylocks, defers, directive, errorsas, httpresponse, ifaceassert, loopclosure, lostcancel, nilfunc, printf, sigchanyzer, slog, sortslice, stdmethods, stringintconv, structtag, testinggoroutine, tests, timeformat, unmarshal, unreachable, unusedresult, waitgroup.

Disabled: shift (nil TypesInfo on external packages).

KTN-MODERNIZE (19 active / 20 total)

Official golang.org/x/tools modernize suite: appendassign, bloop, efaceany, fmtappendf, minmax, omitzero, rangeint, slicesclone, slicescontains, slicesdelete, slicesinsert, sortslice, stringbuilder, stringsseq, testingcontext, unsafefn, waitgroup, forvar, reflecttypefor.

Disabled: newexpr (nil pointer panic).

Statistics

Metric	Value
Go version	1.26+
KTN rules	131
Go Vet rules	27
Modernize rules	20
Total rules	178
Test coverage	99.4%
Packages at 100%	26/31

See COVERAGE.MD for detailed per-package metrics.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
ktn-linter command Package main provides the entry point for the ktn-linter CLI tool.	Package main provides the entry point for the ktn-linter CLI tool.
ktn-linter/cmd Package cmd implements the CLI commands for ktn-linter.	Package cmd implements the CLI commands for ktn-linter.
pkg
analyzer/govet Package govet wraps golang.org/x/tools go vet analyzers.	Package govet wraps golang.org/x/tools go vet analyzers.
analyzer/ktn Package ktn provides the master registry for all KTN lint rules.	Package ktn provides the master registry for all KTN lint rules.
analyzer/ktn/ktnapi Package ktnapi provides analyzers for API design lint rules.	Package ktnapi provides analyzers for API design lint rules.
analyzer/ktn/ktncomment Package ktncomment provides analyzers for comment formatting rules.	Package ktncomment provides analyzers for comment formatting rules.
analyzer/ktn/ktnconst Package ktnconst implements KTN linter rules.	Package ktnconst implements KTN linter rules.
analyzer/ktn/ktnerror Package ktnerror implements KTN linter rules for error handling.	Package ktnerror implements KTN linter rules for error handling.
analyzer/ktn/ktnfunc Package ktnfunc provides analyzers for function-related lint rules.	Package ktnfunc provides analyzers for function-related lint rules.
analyzer/ktn/ktngeneric Package ktngeneric implements KTN linter rules for generic functions.	Package ktngeneric implements KTN linter rules for generic functions.
analyzer/ktn/ktngoroutine Package ktngoroutine provides analyzers for goroutine-related lint rules.	Package ktngoroutine provides analyzers for goroutine-related lint rules.
analyzer/ktn/ktninterface Package ktninterface provides analyzers for interface-related lint rules.	Package ktninterface provides analyzers for interface-related lint rules.
analyzer/ktn/ktniter Package ktniter provides analyzers for Go 1.23+ iterator lint rules.	Package ktniter provides analyzers for Go 1.23+ iterator lint rules.
analyzer/ktn/ktnreceiver Package ktnreceiver provides analyzers for method receiver lint rules.	Package ktnreceiver provides analyzers for method receiver lint rules.
analyzer/ktn/ktnstruct Package ktnstruct provides analyzers for struct-related lint rules.	Package ktnstruct provides analyzers for struct-related lint rules.
analyzer/ktn/ktnswitch Package ktnswitch provides analyzers for switch statement rules.	Package ktnswitch provides analyzers for switch statement rules.
analyzer/ktn/ktntest Package ktntest provides analyzers for test file lint rules.	Package ktntest provides analyzers for test file lint rules.
analyzer/ktn/ktnvar Package ktnvar provides analyzers for variable-related lint rules.	Package ktnvar provides analyzers for variable-related lint rules.
analyzer/ktn/testhelper Package testhelper implements KTN linter rules.	Package testhelper implements KTN linter rules.
analyzer/modernize Package modernize wraps golang.org/x/tools modernize analyzers.	Package modernize wraps golang.org/x/tools modernize analyzers.
analyzer/shared Package shared provides common utilities for static analysis.	Package shared provides common utilities for static analysis.
analyzer/utils Package utils provides AST utility functions for analyzers.	Package utils provides AST utility functions for analyzers.
cache Package cache provides file analysis caching to avoid re-scanning unchanged files.	Package cache provides file analysis caching to avoid re-scanning unchanged files.
config Package config provides configuration management for KTN linter rules.	Package config provides configuration management for KTN linter rules.
formatter Package formatter provides output formatting for lint diagnostics.	Package formatter provides output formatting for lint diagnostics.
messages Package messages provides structured error messages for KTN rules.	Package messages provides structured error messages for KTN rules.
orchestrator Package orchestrator coordinates the linting pipeline.	Package orchestrator coordinates the linting pipeline.
prompt Package prompt provides AI-optimized prompt generation for KTN linter violations.	Package prompt provides AI-optimized prompt generation for KTN linter violations.
rules Package rules provides rule information extraction and formatting utilities.	Package rules provides rule information extraction and formatting utilities.
severity Package severity defines severity levels for lint rules.	Package severity defines severity levels for lint rules.
updater Package updater provides self-update functionality for ktn-linter binary.	Package updater provides self-update functionality for ktn-linter binary.