ktn-linter

README

KTN-Linter

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

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                                         # TTY: explore, non-TTY: lint ./...
ktn-linter lint ./...                              # Lint the entire project
ktn-linter lint --simple ./pkg/...                 # Simplified format
ktn-linter lint --fix ./...                        # Apply auto-fixes in-place
ktn-linter lint --diff ./...                       # Show fixes as unified diff (dry-run)
ktn-linter lint --config .ktn-linter.yaml ./...    # Use a config file
ktn-linter rules --format=markdown                 # Display all rules
ktn-linter explore ./...                           # Interactive directory browser with live file watching

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	- (absolute rule)	-
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 (372 total)

KTN-API (1 rule)

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

KTN-COMMENT (8 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-COMMENT-TODO	INFO	TODO/FIXME comment format (colon + description)

KTN-CONST (7 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-CONST-UNUSED	WARNING	Unused private constant

KTN-ERROR (4 rules)

Code	Severity	Description
KTN-ERROR-ASTYPE	INFO	Prefer errors.AsTypeT (Go 1.26+)
KTN-ERROR-CLOSECHECK	WARNING	Close/Shutdown/Stop error must be checked outside defer
KTN-ERROR-DEFERCLOSE	WARNING	defer Close/Shutdown/Stop must check returned error
KTN-ERROR-DISCARD	WARNING	Error assigned to _ must be logged or propagated
KTN-ERROR-SENTINEL	WARNING	errors.New() should be package-level sentinel
KTN-ERROR-WRAP	WARNING	fmt.Errorf() should wrap errors with %w

KTN-FUNC (23 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	WARNING	Naked returns forbidden when function has return values
KTN-FUNC-NAMEDPARAMS	WARNING	All function parameters and return values must be named
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-FUNC-GENERICPTR	INFO	Use generic Ptr[T] instead of type-specific pointer helpers (Go 1.18+)
KTN-FUNC-NILRETURN	WARNING	Return value always same constant (nil/true/false); consider removing

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 (15 rules)

Code	Severity	Description
KTN-GOROUTINE-ATOMICBOOL	INFO	Mutex+bool replaceable by atomic.Bool
KTN-GOROUTINE-ATOMICINT	INFO	Mutex+int replaceable by atomic.Int64/Int32
KTN-GOROUTINE-ATOMICVAL	INFO	RWMutex+single field replaceable by atomic.Value
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-LOCKSCOPE	WARNING	Unrelated statements inside critical section
KTN-GOROUTINE-ONCEINIT	WARNING	Lock+if !initialized replaceable by sync.Once
KTN-GOROUTINE-PTRRETURN	WARNING	Return pointer to mutex-protected field (data race)
KTN-GOROUTINE-RWOVERMU	INFO	Mutex.Lock() for read-only, use RWMutex.RLock()
KTN-GOROUTINE-SELECT	WARNING	Infinite loop goroutine without exit mechanism
KTN-GOROUTINE-SYNCMAP	INFO	RWMutex+map replaceable by sync.Map
KTN-GOROUTINE-SYNCMAPRACE	WARNING	sync.Map Load+Store race, use LoadOrStore
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 (11 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-UNUSEDTYPE	WARNING	Unused private type
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 (2 rules)

Code	Severity	Description
KTN-SWITCH-EXHAUSTIVE	WARNING	Switch on enum types must cover all values
KTN-SWITCH-MERGECASE	INFO	Switch cases with identical body should be merged

KTN-TEST (28 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-IFACECHECK	WARNING	Interface checks must use compile-time pattern
KTN-TEST-PARALLEL	WARNING	Test functions must call t.Parallel()
KTN-TEST-CONSTCHECK	INFO	Test only verifies constant values
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-TEST-NOPARALLEL	ERROR	t.Parallel() forbidden with global state modification
KTN-TEST-OSENV	WARNING	Prefer t.Setenv() over os.Setenv()/os.Unsetenv()
KTN-TEST-FMTPRINT	WARNING	Prefer t.Log()/t.Logf() over fmt.Print*()
KTN-TEST-CONTEXT	INFO	Prefer t.Context() over context.Background()/TODO()
KTN-TEST-BLOOP	INFO	Prefer b.Loop() over legacy benchmark loop

KTN-VAR (50 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-UNUSEDVAR	WARNING	Unused private package-level variable
KTN-VAR-REGEXPCOMPILE	WARNING	regexp.Compile inside function, move to package var
KTN-VAR-SHORTDECL	INFO	:= vs var (zero-value aware)
KTN-VAR-BLANKASSIGN	INFO	x := f(); _ = x → use _ in := directly
KTN-VAR-DEADASSIGN	INFO	Dead blank assignment (_ = expr) is wasted computation
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-UNCONVERT	INFO	Unnecessary type conversion (same source and target type)
KTN-VAR-DEFERPERF	WARNING	defer Close unnecessary, close immediately for performance
KTN-VAR-REFLECTITER	INFO	Use reflect Fields()/Methods() iterators (Go 1.26+)
KTN-VAR-FMTSPRINT	INFO	fmt.Sprintf replaceable by strconv.Itoa or direct use
KTN-VAR-ESCAPECLOSURE	INFO	Loop closure captures variable causing heap escape
KTN-VAR-NOESCAPE	INFO	&T{} in loop without escape, reuse variable
KTN-VAR-POINTERSTRUCT	INFO	Struct with pointer fields in large collection (GC scan)
KTN-VAR-SORTALLOC	INFO	sort.Slice → slices.SortFunc (Go 1.21+)
KTN-VAR-BYTESCONV	INFO	Repeated string([]byte) on same variable
KTN-VAR-STRINGCONCAT	INFO	String concatenation outside loop (use strings.Builder)

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).

KTN-SC (160 active / 160 total)

All honnef.co/go/tools (staticcheck) analyzers wrapped with KTN-SC- prefix:

• SA (95 rules): Correctness checks — invalid regexp, nil dereference, unused results, concurrency bugs
• S (35 rules): Simplification — unnecessary code patterns, redundant operations
• ST (18 rules): Style — naming conventions, package comments, error strings
• QF (12 rules): Quick fixes — De Morgan's law, if/else to switch, redundant type declarations

Health Advisories

Post-lint meta-analysis that activates only when all lint violations are resolved (0 issues). Health checks operate on package metadata, not AST nodes.

Check	Threshold	Description
PKG-SIZE	20 files	Packages with more than 20 non-test .go files

Health advisories appear as Phase 5 in ktn-linter prompt output and do not affect exit codes.

Statistics

Metric	Value
Go version	1.26+
KTN rules	162
Go Vet rules	27
Modernize rules	20
Staticcheck rules	160
Total rules	372
Test coverage	99.4%
Packages at 100%	26/31

See COVERAGE.MD for detailed per-package metrics.