plans/code-quality-linting.md

Code Quality & Linting Implementation Plan

Overview

Establish comprehensive linting and code quality standards to catch issues early and maintain consistency across the codebase.

Phase 1: golangci-lint Setup (Week 1)

1.1 Configuration File

File: .golangci.yml

run:
  timeout: 5m
  go: '1.24'
  skip-dirs:
    - management-center
    - kiro-gateway

linters:
  enable:
    # Default
    - errcheck
    - gosimple
    - govet
    - ineffassign
    - staticcheck
    - unused
    # Additional
    - bodyclose
    - dogsled
    - dupl
    - exhaustive
    - goconst
    - gocritic
    - gofmt
    - goimports
    - gomnd
    - goprintffuncname
    - gosec
    - misspell
    - nakedret
    - noctx
    - nolintlint
    - prealloc
    - revive
    - stylecheck
    - unconvert
    - unparam
    - whitespace

linters-settings:
  gocritic:
    enabled-tags:
      - performance
      - style
      - experimental
    disabled-checks:
      - wrapperFunc
      - dupImport

  revive:
    rules:
      - name: unexported-return
        disabled: false
      - name: exported
        disabled: false
      - name: package-comments
        disabled: true

  gomnd:
    settings:
      mnd:
        checks:
          - argument
          - case
          - condition
          - operation
          - return
        ignored-numbers:
          - '0'
          - '1'
          - '2'
          - '10'
          - '60'
          - '100'

  dupl:
    threshold: 100

  gosec:
    excludes:
      - G104  # Audit errors not checked (handled by errcheck)

issues:
  exclude-rules:
    # Exclude init() function warnings in translator registrations
    - path: internal/translator/.*/init\.go
      linters:
        - gochecknoinits

    # Exclude underscore variable warnings in test files
    - path: _test\.go
      linters:
        - errcheck

    # Exclude long function warnings in handlers (will refactor separately)
    - path: internal/api/handlers/
      linters:
        - funlen
        - gocognit

  exclude-use-default: false
  max-issues-per-linter: 0
  max-same-issues: 0

1.2 Makefile Targets

File: Makefile (add to existing)

.PHONY: lint lint-fix lint-install

lint-install:
    go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

lint:
    golangci-lint run ./...

lint-fix:
    golangci-lint run --fix ./...

# Pre-commit hook
lint-precommit:
    @echo "#!/bin/sh" > .git/hooks/pre-commit
    @echo 'golangci-lint run --fast ./...' >> .git/hooks/pre-commit
    @chmod +x .git/hooks/pre-commit
    @echo "Pre-commit hook installed"

1.3 Initial Cleanup Tasks

• Fix all goimports issues (import ordering)
• Fix gofmt formatting inconsistencies
• Add missing error checks (errcheck)
• Remove unused variables and imports (unused)
• Fix misspell typos
• Address gosec security warnings
• Fix staticcheck issues

Phase 2: GitHub Actions Integration (Week 1)

File: .github/workflows/lint.yml

name: Lint

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

jobs:
  golangci:
    name: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-go@v5
        with:
          go-version: '1.24'

      - name: golangci-lint
        uses: golangci/golangci-lint-action@v6
        with:
          version: latest
          args: --timeout=5m
          only-new-issues: true

Phase 3: Python Linting (kiro-gateway)

File: kiro-gateway/.pylintrc or kiro-gateway/pyproject.toml

[tool.ruff]
target-version = "py311"
line-length = 100

[tool.ruff.lint]
select = [
    "E",   # pycodestyle errors
    "F",   # Pyflakes
    "I",   # isort
    "N",   # pep8-naming
    "W",   # pycodestyle warnings
    "UP",  # pyupgrade
    "B",   # flake8-bugbear
    "C4",  # flake8-comprehensions
    "SIM", # flake8-simplify
]
ignore = ["E501"]  # Line too long (handled by formatter)

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

Phase 4: TypeScript/React Linting (management-center)

File: management-center/eslint.config.js

import js from '@eslint/js';
import tsParser from '@typescript-eslint/parser';
import tsPlugin from '@typescript-eslint/eslint-plugin';
import reactHooks from 'eslint-plugin-react-hooks';
import reactRefresh from 'eslint-plugin-react-refresh';

export default [
  js.configs.recommended,
  {
    files: ['**/*.{ts,tsx}'],
    languageOptions: {
      parser: tsParser,
      parserOptions: {
        project: './tsconfig.json',
      },
    },
    plugins: {
      '@typescript-eslint': tsPlugin,
      'react-hooks': reactHooks,
      'react-refresh': reactRefresh,
    },
    rules: {
      ...tsPlugin.configs.recommended.rules,
      ...tsPlugin.configs['recommended-requiring-type-checking'].rules,
      ...reactHooks.configs.recommended.rules,
      'react-refresh/only-export-components': 'warn',
      '@typescript-eslint/explicit-function-return-type': 'off',
      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
    },
  },
];

Success Metrics

• Zero linting errors in CI
• All new code passes linting on PR
• Pre-commit hooks installed for all contributors
• Linting time < 2 minutes for full codebase

Estimated Effort

• Week 1: Setup and initial cleanup (16 hours)
• Ongoing: Maintenance as part of PR reviews