code-audit

Code Audit

Аудит качества кода с использованием SAST tools и ручного анализа.

Принципы

1. Tools first, manual review second - tools находят явное, manual review находит структурное
2. Hot paths приоритетнее cold paths - cycle complexity 30 в часто меняемом коде хуже чем 50 в стабильном
3. Не все findings равны - tool может найти 500 issues, реально важных 30

Workflow

C1. Tool execution

Через skill tooling-<lang> для каждого языка проекта:

• Python → tooling-python skill
• JS/TS → tooling-js-ts skill
• Go → tooling-go skill

В quick mode - skip SAST tools. В standard - все. В deep - все + manual review топ-5 hot files.

Сохрани сырые выходы в docs/audit/<TS>/code/tooling-output/.

C2. Hot files identification

# Files most frequently changed
git log --pretty=format: --name-only --since="6 months ago" \
  | grep -v '^$' \
  | sort | uniq -c | sort -rg | head -20

Hot files имеют immediate priority - findings в них критичнее.

C3. Aggregation and noise filtering

Tool output типично содержит много noise. Skill должен:

1. Дедуплицировать - один issue найденный двумя tools = один finding
2. Группировать по category - SOLID, complexity, duplication, dead code, naming, ...
3. Отбрасывать style-only - если есть formatter (black, prettier, gofmt) и code passes - не делать findings из style
4. Приоритизировать hot paths - file is in top-20 hot list → severity bump

C4. SOLID Analysis

Single Responsibility (SRP):

• Файл/класс с >5 different concerns
• Detection: count public methods, group by similar verb prefixes

Open/Closed (OCP):

• Сложно расширить без модификации
• Detection: switch statements/if-elif chains на тип/вид
• Например: if order.type == 'standard': ... elif order.type == 'express': ... повторяющееся в 5 местах = bad

Liskov Substitution (LSP):

• Subclass нарушает контракт parent
• Detection: чтение базовых классов и subclasses, проверка assert/raise patterns

Interface Segregation (ISP):

• Implementations forced to implement methods они не используют
• Detection: смотреть abstract base classes / interfaces, есть ли raise NotImplementedError в subclasses

Dependency Inversion (DIP):

• High-level module зависит от low-level concrete instead of abstraction
• Detection: imports concrete classes из infrastructure layer in domain layer

C5. Complexity Hotspots

Создай docs/audit/<TS>/code/complexity-hotspots.md:

Таблица топ-20 функций/методов по metrics:

Function	File:Line	CC	Cognitive	LOC	Hot file?
process_order	apps/sales/views.py:142	35	47	187	YES
...

Cyclomatic Complexity > 30 - critical (very hard to test, very bug-prone). Cognitive Complexity (Sonar) часто более полезный indicator.

C6. Duplication Report

Создай docs/audit/<TS>/code/duplication-report.md:

Группы duplicated blocks (>10 LOC matches), сортировка по:

• Размер дубля
• Количество мест
• Hot path или нет

Tools:

• Python: pylint --disable=all --enable=duplicate-code
• JS/TS: jscpd
• Go: dupl

C7. Dead Code

Tool-based:

• Python: vulture (warning: false positives для introspection-based code типа Django)
• JS/TS: knip (best для modern projects), ts-unused-exports
• Go: deadcode, staticcheck partial

Manual: смотреть commits messages "TODO remove", "deprecated", "old version"

C8. Other Code Smells

• Long methods (>50 LOC)
• Long classes (>300 LOC)
• Deep nesting (>4 levels)
• Magic numbers без named constants
• Comments describing what (smell - the code should be readable) vs why (good)
• Naming: data, info, manager, helper, util - generic uninformative names
• Too many parameters (>5 - consider parameter object)

Severity Application

См. severity rules в audit-code.md команды.

Output

Findings в docs/audit/<TS>/code/findings.json.

Supporting артефакты:

• complexity-hotspots.md
• duplication-report.md
• tooling-output/ (raw tool outputs)

Manual review (deep mode only)

Прочитать топ-5 hot files. Для каждого оценить:

• Файл понятен в первое прочтение?
• Имена коммуникативные?
• SOLID adherence на класс/метод уровне?
• Test coverage этого файла high?
• Если бы writing from scratch today - сделал бы так же или лучше есть варианты?

Записать observations в finding'ах.