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`

```yaml
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)

```makefile
.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`

```yaml
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`

```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`

```javascript
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