loki5512344
c3b8d4dd62
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
70 lines
4.4 KiB
Markdown
70 lines
4.4 KiB
Markdown
# Документация noxis
|
||
|
||
Обфускатор JVM/Java-байткода на Rust. Этот файл — индекс.
|
||
|
||
## Что где
|
||
|
||
| файл | что внутри |
|
||
|---|---|
|
||
| [`architecture.md`](architecture.md) | слои, крейты, собственный IR, конвейер пассов, структурные правила |
|
||
| [`techniques.md`](techniques.md) | как работает каждая техника + плюсы/минусы/цена |
|
||
| [`stack.md`](stack.md) | почему свой IR, какой backend, `StackMapTable`, PRNG, генерация рантайма |
|
||
| [`learnings/lessons.md`](learnings/lessons.md) | уроки из разбора EvoVis: что защита сделала плохо и чего мы не делаем |
|
||
| [`learnings/reference.md`](learnings/reference.md) | разбор референсного обфускатора (Java/ASM) — что берём, что нет |
|
||
| [`learnings/priorities.md`](learnings/priorities.md) | что улучшим: стратегия и приоритеты |
|
||
| [`learnings/ai-resistance.md`](learnings/ai-resistance.md) | новые техники обфускации и устойчивость к LLM-анализу |
|
||
|
||
План выполнения — [`../todo.md`](../todo.md). Исходный материал разбора —
|
||
[`../info/`](../info/README.md).
|
||
|
||
## Структурные правила проекта
|
||
|
||
Правила — **только про Rust-код**: `crates/*/src`, `crates/*/tests`,
|
||
`crates/*/benches`. Документация (`docs/**`, корневые `.md`) и `info/` вне
|
||
гейта: писать подробно там, где это документация, а не ограничивать объём
|
||
искусственно. Не учитываются также `Cargo.lock`, `.gitignore`, корень крейта
|
||
(в нём всегда лежат `Cargo.toml` + `build.rs`).
|
||
|
||
1. **Не больше 250 строк** в одном `.rs` файле.
|
||
2. **Не больше 4 `.rs`-файлов** в одной директории. Подпапки не ограничены:
|
||
`src/` может содержать `lib.rs` и три модуля-директории, каждая из которых
|
||
в свою очередь содержит не больше четырёх файлов.
|
||
|
||
`tests/` и `benches/` не исключены намеренно — иначе правило
|
||
«250 строк» обходится выносом кода в тесты.
|
||
|
||
Правило 2 — это не косметика: файл из тысячи строк означает, что в нём
|
||
смешаны разные причины к изменению (нарушение KISS/DRY/SOLID), а команда из
|
||
восьми файлов в одной папке — что модуль перестал быть модулем.
|
||
|
||
### Как проверяется
|
||
|
||
Правила гоняются **при компиляции**. Каждый крейт имеет `build.rs`:
|
||
|
||
```rust
|
||
fn main() {
|
||
noxis_structure_check::check();
|
||
}
|
||
```
|
||
|
||
`noxis-structure-check` обходит деревья `src/`, `tests/` и `benches/` **этого
|
||
крейта** и **падает со стопкой ошибок**, если лимит нарушен. Поэтому
|
||
`cargo build` не соберёт нарушение — специально запускать проверку не нужно.
|
||
Деревья регистрируются через `cargo:rerun-if-changed`, чтобы гейт не
|
||
срабатывал на правки вне проверяемых путей.
|
||
|
||
Остальное, что не привязано к компиляции, собирается одним скриптом:
|
||
|
||
```sh
|
||
./scripts/check.sh # structure → fmt → clippy -D warnings → test
|
||
```
|
||
|
||
### Что делать при нарушении
|
||
|
||
- файл разрослся → разрезать по одной ответственности на файл:
|
||
`mod.rs` = публичный контракт модуля, соседние файлы — внутренности;
|
||
- папка переполнилась → завести подпапку и вынести подфункцию целиком,
|
||
а не «чтобы влезло».
|
||
|
||
Каждый модуль получает `mod.rs` с `//!`-документацией — это точка входа,
|
||
читающаяся вместо пяти файлов.
|