strictacode 0.0.1__tar.gz

strictacode-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 1
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

strictacode-0.0.1/.gitignore

@@ -0,0 +1,210 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# tmp docs
+docs/plans

strictacode-0.0.1/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: strictacode
+Version: 0.0.1
+Summary: Codebase health diagnostics
+License: BSD 3-Clause
+Project-URL: Homepage, https://github.com/qarium/strictacode
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: numpy
+Requires-Dist: radon
+Requires-Dist: click

strictacode-0.0.1/README.md

@@ -0,0 +1,133 @@
+# Strictacode
+
+**Диагностика здоровья кодовой базы.**
+
+Strictacode находит болевые точки проекта: спагетти-код, overengineering и сложность, которая блокирует разработку.
+
+> Работает с AI-агентами для автоматического анализа качества кода.
+
+> Легко интегрируется в CI/CD пайплайны и локальный REPL-цикл разработки.
+
+---
+
+## Поддерживаемые языки
+
+Golang · Python · Javascript
+
+---
+
+## Быстрый старт
+
+```bash
+pip install strictacode
+strictacode analyze . --short
+```
+
+Результат не очевиден? См. [Интерпретация метрик](docs/interpretation.md) — там сценарии и рекомендации.
+
+---
+
+## Зачем это нужно
+
+Вы когда-нибудь заходили в "наследственный" проект и думали: *с чего начать?*
+Или смотрели на отчёт о покрытии тестами и понимали: *это не показывает реальную проблему*.
+
+Strictacode отвечает на вопрос: **насколько больно работать с этим кодом?**
+
+Он не считает строки. Он ищет:
+- Функции, которые сложно изменить без багов
+- Архитектуру, которая слишком сложная для задачи
+- Места, где техдолг уже блокирует разработку
+
+---
+
+## Как это работает
+
+```
+$ strictacode analyze ./src --short
+
+Project:
+  * status:
+    - name: warning
+    - score: 58          ← здоровье проекта (0-100, меньше = лучше)
+  * refactoring_pressure:
+    - score: 72          ← насколько код "давит" на разработчика
+  * overengineering_pressure:
+    - score: 18          ← насколько архитектура избыточна
+  * complexity:
+    - density: 42.5      ← концентрация сложности
+```
+
+Вы узнаете:
+- **Spaghetti** (RP высокий, OP низкий) → чистите функции
+- **Overengineering** (OP высокий, RP низкий) → упрощайте архитектуру
+- **Кризис** (оба высокие) → изолируйте и переписывайте
+- **Здоровый** (оба низкие) → мониторьте
+
+---
+
+## Метрики
+
+| Метрика                      | Что измеряет            | Хорошо | Плохо  |
+|------------------------------|-------------------------|--------|--------|
+| **Project Score**            | Общее здоровье          | 0-20   | 60+    |
+| **Refactoring Pressure**     | Давление на рефакторинг | 0-40   | 60+    |
+| **Overengineering Pressure** | Избыточная сложность    | 0-40   | 60+    |
+| **Complexity Density**       | Плотность сложности     | < 20   | > 50   |
+
+---
+
+## Когда использовать
+
+| Ситуация                  | Что даст strictacode                                      |
+|---------------------------|-----------------------------------------------------------|
+| Оценка техдолга           | Оцифрует "код плохой" в метрики для менеджмента           |
+| Планирование тестирования | Укажет, какие проекты/компоненты требуют больше внимания  |
+| Планирование рефакторинга | Укажет, где "80% боли от 20% кода"                        |
+| Ретроспектива спринта     | Объективные данные вместо субъективных оценок             |
+| Onboarding в проект       | Покажет, какие модули самые сложные                       |
+| CI/CD pipeline            | Заблокирует деградацию качества                           |
+
+---
+
+## Команды
+
+```bash
+# Полный отчёт
+strictacode analyze <path>
+
+# Короткий отчёт
+strictacode analyze <path> --short
+
+# Детализация по модулям, классам, функциям
+strictacode analyze <path> --details
+
+# JSON формат для CI/CD
+strictacode analyze <path> --format json
+```
+
+---
+
+## Интеграция с AI-агентами
+
+Strictacode может быть установлен как навык (skill) в AI-агенты для автоматического анализа качества кода:
+
+```bash
+strictacode install agent-skill --agent <agent_name>
+```
+
+Поддерживаемые агенты:
+- `claude`
+- `cursor`
+- `codex`
+- `gemini`
+- `antigravity`
+
+---
+
+## Документация
+
+- [Поля отчёта](docs/report-fields.md) — описание всех полей в отчёте с типами и примерами
+- [Как рассчитываются метрики](docs/metrics.md) — формулы и математика
+- [Интерпретация метрик](docs/interpretation.md) — сценарии анализа и рекомендации
+- [Примеры использования](docs/examples.md) — реальные сценарии и алгоритмы действий

strictacode-0.0.1/docs/examples.md

@@ -0,0 +1,270 @@
+# Примеры использования
+
+Эта документация содержит реальные сценарии использования strictacode с пошаговыми алгоритмами действий.
+
+---
+
+## Содержание
+
+- [Знакомство с проектом](#знакомство-с-проектом)
+- [Повседневная разработка](#повседневная-разработка)
+- [Принятие решений](#принятие-решений)
+- [Процессы команды](#процессы-команды)
+
+---
+
+## Знакомство с проектом
+
+### Onboarding новичка
+
+**Контекст:** Новый разработчик приходит в проект. Первая задача — понять, где сложный код, а где можно работать спокойно. Без strictacode это недели чтения кода и случайные открытия.
+
+**Команда:**
+```bash
+strictacode analyze . --details
+```
+
+**Результат:** Метрики по модулям/пакетам — где высокий RP (грязный код), где высокий OP (сложные связи), где density зашкаливает.
+
+**Алгоритм:**
+1. Запустить анализ с `--details`
+2. Найти модули с `status: healthy` — начинать работу лучше с них
+3. Посмотреть модули с `RP > 60` — там сложнее всего вносить изменения
+4. Изучить `density` — высокая плотность означает "спагетти в одном файле"
+5. Составить мысленную карту: "зелёные зоны" vs "красные зоны"
+
+---
+
+### Оценка наследственного проекта
+
+**Контекст:** Tech lead заходит в унаследованный проект. Нужно быстро понять состояние кодовой базы и ответить на вопрос: "с чего начать?"
+
+**Команда:**
+```bash
+strictacode analyze . --short
+```
+
+**Результат:** Project Score, RP, OP, density — общая картина здоровья.
+
+**Алгоритм:**
+1. Запустить короткий анализ — получить Project Score
+2. Интерпретировать score по шкале (healthy/normal/warning/critical/emergency)
+3. Сравнить RP и OP:
+   - RP >> OP → spaghetti-код, чистить функции
+   - OP >> RP → overengineering, упрощать архитектуру
+   - Оба высокие → кризис, изолировать и переписывать
+4. Сформировать отчёт для стейкхолдеров с конкретными метриками
+
+---
+
+## Повседневная разработка
+
+### Планирование юнит-тестов
+
+**Контекст:** Разработчик планирует, какие функции покрыть unit-тестами в первую очередь. Ограниченное время — нужно найти максимальный выхлоп.
+
+**Команда:**
+```bash
+strictacode analyze . --details
+```
+
+**Результат:** Детализация по модулям/классам/функциям с метриками сложности.
+
+**Алгоритм:**
+1. Запустить анализ с `--details`
+2. Отсортировать функции по `complexity` — функции с complexity > 15 труднее тестировать и быстрее ломаются
+3. Смотреть на `density` в модуле — высокая плотность означает запутанный код, тесты будут сложными
+4. Приоритет: сначала функции с высокой complexity в модулях с низким OP (меньше моков)
+5. Функции в модулях с высоким OP отложить — там нужны интеграционные тесты
+
+---
+
+### Планирование интеграционных тестов на сервисы
+
+**Контекст:** QA планирует тестирование микросервисной архитектуры. Нужно понять, какие сервисы изменяются с большими рисками, какие — с меньшими.
+
+**Команда:**
+```bash
+# Для каждого сервиса
+strictacode analyze ./service-a --short
+strictacode analyze ./service-b --short
+strictacode analyze ./service-c --short
+```
+
+**Результат:** Project Score, RP, OP, density по каждому сервису.
+
+**Алгоритм:**
+1. Запустить анализ для каждого сервиса отдельно
+2. Сравнить метрики между сервисами:
+   - Высокий RP — сервис с "грязным" кодом, изменения рискованны
+   - Высокий OP — сложная архитектура, выше шанс сломать интеграции
+   - Высокий density — много логики в одном месте, сложнее покрыть тестами
+3. Приоритет тестирования:
+   - `status: critical/emergency` — максимальное внимание, regression-тесты обязательны
+   - `status: warning` — стандартное покрытие + smoke-тесты интеграций
+   - `status: healthy/normal` — минимальный набор smoke-тестов
+4. Заложить буфер времени на баги в сервисах с высоким RP
+
+---
+
+### Приоритизация API-ручек для тестирования
+
+**Контекст:** В сервисе много API-эндпоинтов, все протестировать невозможно. Нужно понять, какие ручки покрывать тестами в первую очередь.
+
+**Команда:**
+```bash
+strictacode analyze . --details
+```
+
+**Результат:** Детализация по пакетам/модулям с метриками.
+
+**Алгоритм:**
+1. Запустить анализ с `--details`
+2. Найти пакеты с `status: warning` и выше — это проблемные зоны
+3. Сопоставить пакеты с API-ручками:
+   - Какой пакет обрабатывает какую ручку
+   - Какие ручки зависят от модулей с высоким RP
+4. Приоритет тестирования ручек:
+   - Ручки на базе пакетов с `status: critical` — тестировать первыми, максимальное покрытие
+   - Ручки на базе пакетов с `status: warning` — стандартное покрытие
+   - Ручки на базе пакетов с `status: healthy` — минимальные smoke-тесты
+5. Ручки, которые затрагивают несколько проблемных модулей — кандидаты на end-to-end тесты
+
+---
+
+## Принятие решений
+
+### Выбор: переписывать или рефакторить пакет/сервис
+
+**Контекст:** Целый пакет или сервис проблемный. Нужно решить на уровне архитектурной единицы.
+
+**Команда:**
+```bash
+strictacode analyze .
+```
+
+**Результат:** Метрики проекта с разбивкой по пакетам/модулям.
+
+**Алгоритм:**
+1. Запустить анализ всего проекта
+2. Найти нужный пакет/сервис в результатах
+3. Оценить общее состояние через его Project Score:
+   - Score < 40 — можно рефакторить постепенно
+   - Score 40-60 — серьёзные проблемы, нужен план
+   - Score > 60 — критическое состояние
+4. Посмотреть распределение проблем внутри:
+   - Проблемы в 1-2 подмодулях → изолировать и рефакторить/переписать только их
+   - Проблемы распределены равномерно → системная проблема архитектуры
+5. Оценить связи (OP): высокий OP означает, что модуль сильно связан с другими. Переписывание сломает интеграции.
+6. Решение:
+   - Локальные проблемы → точечный рефакторинг/переписывание
+   - Системные проблемы + низкий OP → кандидат на переписывание
+   - Системные проблемы + высокий OP → постепенный рефакторинг с сохранением интерфейсов
+
+---
+
+### Обоснование рефакторинга менеджменту
+
+**Контекст:** Нужно выделить время на рефакторинг в спринте. Менеджмент хочет понять: "зачем?" и "сколько?". Субъективное "код плохой" не работает.
+
+**Команда:**
+```bash
+strictacode analyze . --short
+strictacode analyze . --format json > quality-baseline.json
+```
+
+**Результат:** Метрики в читаемом виде + JSON для отслеживания прогресса.
+
+**Алгоритм:**
+1. Запустить анализ, сохранить baseline
+2. Сформулировать проблему через метрики:
+   - "RP = 72 — это значит, что каждое изменение кода несёт высокий риск багов"
+   - "Density = 58 — код спагетти-подобный, время на задачу увеличивается в 2 раза"
+3. Показать тенденцию: запустить анализ на коде 3-месячной давности (git checkout), сравнить
+4. Перевести в бизнес-язык:
+   - Высокий RP → медленнее фичи, больше багов в проде
+   - Высокий OP → сложнее onboardить новичков, дольше code review
+5. Предложить план: "Снизим RP с 72 до 40 за 2 спринта, это ускорит разработку на X%"
+6. После рефакторинга: запустить анализ снова, показать динамику
+
+---
+
+## Процессы команды
+
+### Ретроспектива спринта
+
+**Контекст:** Команда проводит ретро. Обсуждаем качество кода. Мнения расходятся: "нормальный код" vs "всё разваливается". Нужны объективные данные.
+
+**Команда:**
+```bash
+# До спринта
+strictacode analyze . --format json > sprint-start.json
+
+# После спринта
+strictacode analyze . --format json > sprint-end.json
+```
+
+**Результат:** Два снапшота состояния кодовой базы.
+
+**Алгоритм:**
+1. Запустить анализ в начале спринта, сохранить baseline
+2. В течение спринта — не трогать, просто работать
+3. В конце спринта — запустить анализ снова
+4. Сравнить метрики:
+   - RP вырос → накопили техдолг, следующий спринт нужно заложить время на чистку
+   - OP вырос → добавили абстракций, проверить — они нужны или преждевременны?
+   - Density вырос → начали писать "грязный" код, нужен code review строже
+5. Обсудить на ретро:
+   - Какие модули ухудшились и почему?
+   - Это нормальный рост или проблема?
+   - Что сделать в следующем спринте?
+6. Сохранить sprint-end.json как baseline для следующего спринта
+
+---
+
+### CI/CD гейты
+
+**Контекст:** Нужно заблокировать деградацию качества кода в пайплайне. Pull request с плохим кодом не должен попадать в main.
+
+**Команда (в CI):**
+```bash
+strictacode analyze . --format json > current.json
+```
+
+**Результат:** JSON-отчёт для автоматической проверки.
+
+**Алгоритм:**
+1. Определить baseline: запустить анализ на текущем main, сохранить `baseline.json` в репозиторий
+2. В CI-пайплайне добавить шаг после тестов:
+   - Запустить `strictacode analyze . --format json > current.json`
+   - Сравнить `current.json` с `baseline.json` по ключевым метрикам
+3. Блокировать PR если:
+   - Project Score вырос выше порога (например, > 60)
+   - RP вырос больше чем на N пунктов относительно baseline
+4. После мерджа в main — обновить `baseline.json`
+
+**Пример проверки (Python скрипт):**
+```python
+import json
+
+THRESHOLD_SCORE = 60
+THRESHOLD_RP_DIFF = 10
+
+with open("baseline.json") as f:
+    baseline = json.load(f)
+with open("current.json") as f:
+    current = json.load(f)
+
+score = current["project"]["status"]["score"]
+rp_diff = current["project"]["refactoring_pressure"]["score"] - baseline["project"]["refactoring_pressure"]["score"]
+
+if score > THRESHOLD_SCORE:
+    print(f"FAIL: Project Score {score} > {THRESHOLD_SCORE}")
+    exit(1)
+
+if rp_diff > THRESHOLD_RP_DIFF:
+    print(f"FAIL: RP вырос на {rp_diff} пунктов (порог: {THRESHOLD_RP_DIFF})")
+    exit(1)
+
+print("OK: Метрики в пределах нормы")
+```