loki5512344 c3b8d4dd62 docs: sync status with code, add AI-resistance research, restyle README

Documentation had drifted from the actual implementation: the noxis
(CLI) and noxis-verify crates were fully built and tested but every
doc called them "not started". Verified against the code (build +
test run) and corrected status across README.md, todo.md,
architecture.md, techniques.md and learnings/{lessons,priorities}.md.

Also:
- restyled README.md (badges, no em dashes, usage examples, dropped
  the redundant "Принципы" section already covered elsewhere)
- added docs/learnings/ai-resistance.md: a sourced writeup of what
  actually works against LLM-driven reverse engineering (Elastic
  Security Labs' Opus 4.6 vs Tigress study, the Acoda paper) and what
  of it applies to noxis, plus concrete todo.md §7 items
- noxis-structure-check: the 250-line/4-file gate was scanning
  docs/**, which fought against writing documentation freely; it now
  only scans crates/*/{src,tests,benches} and only counts .rs files

2026-10-08 22:34:00 +02:00

4.4 KiB

Raw Blame History

Документация noxis

Обфускатор JVM/Java-байткода на Rust. Этот файл — индекс.

Что где

файл	что внутри
`architecture.md`	слои, крейты, собственный IR, конвейер пассов, структурные правила
`techniques.md`	как работает каждая техника + плюсы/минусы/цена
`stack.md`	почему свой IR, какой backend, `StackMapTable`, PRNG, генерация рантайма
`learnings/lessons.md`	уроки из разбора EvoVis: что защита сделала плохо и чего мы не делаем
`learnings/reference.md`	разбор референсного обфускатора (Java/ASM) — что берём, что нет
`learnings/priorities.md`	что улучшим: стратегия и приоритеты
`learnings/ai-resistance.md`	новые техники обфускации и устойчивость к LLM-анализу

План выполнения — ../todo.md. Исходный материал разбора — ../info/.

Структурные правила проекта

Правила — только про Rust-код: crates/*/src, crates/*/tests, crates/*/benches. Документация (docs/**, корневые .md) и info/ вне гейта: писать подробно там, где это документация, а не ограничивать объём искусственно. Не учитываются также Cargo.lock, .gitignore, корень крейта (в нём всегда лежат Cargo.toml + build.rs).

Не больше 250 строк в одном .rs файле.
Не больше 4 .rs-файлов в одной директории. Подпапки не ограничены: src/ может содержать lib.rs и три модуля-директории, каждая из которых в свою очередь содержит не больше четырёх файлов.

tests/ и benches/ не исключены намеренно — иначе правило «250 строк» обходится выносом кода в тесты.

Правило 2 — это не косметика: файл из тысячи строк означает, что в нём смешаны разные причины к изменению (нарушение KISS/DRY/SOLID), а команда из восьми файлов в одной папке — что модуль перестал быть модулем.

Как проверяется

Правила гоняются при компиляции. Каждый крейт имеет build.rs:

fn main() {
    noxis_structure_check::check();
}

noxis-structure-check обходит деревья src/, tests/ и benches/ этого крейта и падает со стопкой ошибок, если лимит нарушен. Поэтому cargo build не соберёт нарушение — специально запускать проверку не нужно. Деревья регистрируются через cargo:rerun-if-changed, чтобы гейт не срабатывал на правки вне проверяемых путей.

Остальное, что не привязано к компиляции, собирается одним скриптом:

./scripts/check.sh   # structure → fmt → clippy -D warnings → test

Что делать при нарушении

файл разрослся → разрезать по одной ответственности на файл: mod.rs = публичный контракт модуля, соседние файлы — внутренности;
папка переполнилась → завести подпапку и вынести подфункцию целиком, а не «чтобы влезло».

Каждый модуль получает mod.rs с //!-документацией — это точка входа, читающаяся вместо пяти файлов.

4.4 KiB Raw Blame History Unescape Escape